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

With no annotations, the description must carry the full burden of behavioral disclosure. It mentions 'record state' and 'provision agent & skill' but does not explain what state is recorded, where it is stored, whether the operation is idempotent, what permissions are required, or what side effects occur. This is a significant gap for an initialization 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?

The description is a single, front-loaded sentence that efficiently lists the main actions. It is concise but may be overly terse given the tool's complexity.

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 that likely performs multiple significant operations (model detection, skill provisioning, state recording), the description is far too sparse. With no annotations, no output schema, and an undocumented parameter, it leaves critical details about behavior and return values unspecified.

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 does not mention the sole parameter `project_root`. While the parameter name is self-explanatory, the description fails to compensate for the missing schema annotation by explaining format, constraints, or what the path is used for.

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 ('Bootstrap') and lists three sub-actions (detect model, provision agent & skill, record state), which conveys the general purpose. However, it does not differentiate from sibling tools like detect_model or provision_agent_skill that perform the same individual actions, leaving the agent unsure when to use this composite tool versus calling those siblings 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?

No guidance is given on when to use this tool, when not to, or what alternatives exist. The description simply lists steps without context about prerequisites, session phases, or expected call order relative to siblings like init_plan or detect_model.

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 no annotations, the description carries the full behavioral burden and does disclose the optional playwright/puppeteer requirement and fallback to webfetch. It still omits important behavioral details such as return format, screenshot handling, error behavior, and whether fallback changes the 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?

The description is two compact sentences with no wasted wording, and the core capability is front-loaded. Both sentences contribute useful information about rendering and dependency/fallback behavior.

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 are no annotations, no output schema, and weak schema description coverage for two of three parameters. The description covers the headline capability and dependency, but it does not provide enough context about return values, parameter effects, or fallback semantics for an agent to fully understand the 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?

Only the url parameter is documented in the schema, while max_chars and timeout_ms have constraints but no descriptions. The tool description does not mention any parameters, so it fails to compensate for the low 33% schema description coverage.

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 gives a specific verb and resource: fetch a URL using a headless browser, with JS-rendered pages and screenshots called out. It partially distinguishes itself from sibling webfetch by mentioning the fallback, but it does not clearly state the primary selection rule versus webfetch.

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 'JS-rendered, screenshots' and the optional playwright/puppeteer dependency, suggesting this is for pages needing browser rendering. However, there is no explicit guidance on when to choose browser_fetch over webfetch when both are available, and no exclusions are stated.

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

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

No annotations are provided, so the description carries the full burden, yet it says nothing about whether this is read-only, what it returns, whether it is cheap or expensive, or whether it depends on session/bootstrap state (e.g., bootstrap_session). For an unannotated tool that is a serious gap.

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 padding, but the brevity here comes from under-specification rather than discipline; the one sentence does not carry enough information to earn its place as the entire definition.

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 annotations, no output schema, and an undocumented parameter, the description should explain what the summary contains and what project_root does. It does none of that, leaving the agent unable to predict the response or call semantics.

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 parameter project_root has 0% schema description coverage, and the description never mentions it. Whether the root selects the session, is optional (required list is empty), or affects the returned status is left entirely to guesswork, so the description fails to 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?

The description largely restates the name: 'cognitive_status' becomes 'Cognitive status summary.' The only added information is the scope phrase 'for the current session,' and the term 'cognitive status' is never defined, so an agent cannot tell what data would actually come back or how this differs from siblings like memory_stats, system_stats, or decision_health.

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

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

There is no guidance on when to call this tool, when not to, or which sibling to prefer among the many status/stats tools (memory_stats, system_stats, decision_health, task_summary). 'For the current session' hints at scope but gives no selection criteria.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, yet it says nothing about side effects, determinism, permissions, or whether it mutates stored state. 'Internal' is the only behavioral hint and is ambiguous rather than informative.

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

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

It is a single short, front-loaded sentence with no filler, which is good, but the parenthetical '(tier/risk/route/compliance)' is cryptic shorthand rather than an earned explanation. Brevity here reflects under-specification as much as efficiency.

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

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

For a two-parameter classification tool with no annotations and no output schema, the description omits everything an agent needs: the semantics of the required 'state' input, what 'questions' is for, and what the returned classification looks like. Only the output categories are named.

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%: 'state' (required, minLength 1) and the untyped 'questions' property are completely undocumented in the schema, and the description adds no meaning for either. An agent has no idea what to pass as 'state' or what shape 'questions' should take.

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 verb (classify) and a resource (decisions) and enumerates the classification dimensions it produces (tier/risk/route/compliance). However, it gives no indication of what a 'decision' is here or how it differs from siblings like decision_health or model_decision, so the agent cannot confidently route to it.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools such as decision_health or model_decision. The word 'Internal' vaguely hints at a system-level call but does not tell the agent when this tool is appropriate.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about whether this is a read-only probe, what it measures, whether it is cheap or expensive, or what it returns. For a monitoring endpoint this is a substantial gap.

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 fragment with no padding, which satisfies conciseness, but it reads as an incomplete label rather than a front-loaded statement. Brevity here reflects under-specification as much as 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?

Zero params and no output schema make this a simple tool, but the description never explains what the 'health' result represents or what an agent should do with it. The minimum context needed to invoke it purposefully is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level information is missing.

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 'Health of the internal decision engine' is a noun fragment that essentially restates the tool name decision_health; it names no verb (check, get, report) and gives no sense of what 'health' means. It is closer to a tautology than a statement of what the tool does.

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

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

There is no indication of when to call this versus the many sibling diagnostics such as cognitive_status, system_stats, or get_guardrails. An agent must guess at the trigger condition entirely.

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?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about precedence between env, config, and arg, what happens when no model is detected, or whether the call is read-only and side-effect free. The mention of resolution sources is the only behavioral hint.

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?

One short sentence with no wasted words, but it is terse to the point of under-specification rather than dense with useful information. The most important detail, the precedence order, is compressed into an ambiguous slash-list.

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 annotations and no output schema, the description should explain what is returned (e.g., the detected model name, or a fallback) and how detection failure is reported, but it does none of this. For a detection tool whose whole value is the resolution logic, this is a notable gap.

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

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

Schema description coverage is 0%, so the description must compensate, but 'env/config/arg' only loosely maps to the 'model' parameter and leaves 'project_root' completely unexplained (presumably the location of the config to inspect). Neither parameter's format, defaults, or interaction is clarified.

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 ('Detect the model in use') and adds the resolution sources ('env/config/arg'), so an agent knows what the tool returns conceptually. However, it does not distinguish itself from siblings like get_model_profile, set_model, or model_decision, which all concern model configuration.

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

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

There is no guidance on when to call this instead of get_model_profile or model_decision, and no preconditions or exclusions are stated. The agent must infer usage entirely from the tool name.

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?

No annotations are provided, so the description carries the full behavioral burden. It only implies a read operation via 'Get' and omits return shape, side effects, auth requirements, and whether guardrails are computed or stored.

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 repetition. It is efficient, though the brevity contributes to under-specification in other dimensions.

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 three parameters, no annotations, no output schema, and 0% schema coverage, the definition lacks enough detail for reliable invocation. It provides no parameter semantics, no return information, and no sibling routing guidance.

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 mentions only task/model while leaving project_root unexplained. It gives no format, meaning, or requiredness details for any of the three parameters.

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 'Get' and resource 'procedure guardrails (anti-blunder)' scoped to a task/model. The parenthetical clarifies the concept, but the description does not differentiate it from siblings such as get_procedure or retrieve_exemplars.

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 guidance, no exclusions, and no named alternatives. The phrase 'for a task/model' supplies only a vague context, not selection criteria versus sibling tools.

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?

No annotations are provided, so the description carries the full burden. 'Get' implies a read operation, but the description does not state read-only behavior, error handling for an unknown model, or what a 'tier' value looks like — all of which matter for a lookup tool with zero structured hints.

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?

One short, front-loaded sentence with no filler. It is appropriately sized, though it is terse rather than richly structured.

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

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

With no output schema and no annotations, an agent has no idea what the response shape is beyond the words 'tier' and 'capabilities', nor what valid inputs look like. For a lookup tool that must be called correctly on the first try, this leaves significant 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 'model' parameter has 0% schema description coverage, and the description adds nothing about its expected format (identifier, display name, provider prefix). This is the one place the description could have compensated for the schema gap and it does not.

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?

A specific verb ('Get') plus resource ('model profile') with a parenthetical naming the returned fields (tier, capabilities). It does not explicitly differentiate itself from sibling tools like detect_model, set_model, or model_decision, 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 description offers no when-to-use guidance, no prerequisites, and never references the obvious alternatives (detect_model for identification, set_model for changing it, model_decision for routing). An agent must infer the distinction from names alone.

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 no annotations, the description carries the full disclosure burden, and it says only 'Get.' It implies a safe read but does not state permissions, whether a missing name errors or returns empty, or what is returned; a getter with zero annotation coverage needs more than this.

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?

One short, front-loaded sentence with no wasted words. It is appropriately sized for a trivial getter, though the brevity reflects under-specification rather than tight information density.

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 getter with no output schema, the definition is minimally workable, but it omits lookup/return semantics and missing-record behavior. No annotations or output schema exist to fill those gaps.

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

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

Schema description coverage is 0% and the single `name` parameter has no description, so the description should compensate. 'By name' merely restates the parameter identifier already visible in the schema and adds no format, casing, or matching guidance.

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 ('Get a procedure') and adds the retrieval key ('by name'), so the operation is unambiguous. It does not explicitly differentiate from the sibling `list_procedures` or `update_procedure_block`, 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 guidance, no condition for choosing this over `list_procedures`, and no mention of prerequisites or error behavior when the name is unknown. 'By name' implies the lookup key but leaves usage entirely to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers almost nothing. 'Ingest' implies a persistent write, but there is no disclosure of what gets stored, whether duplicates are deduplicated or embedded, whether the operation is reversible, or what permissions are needed.

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 one short sentence with no wasted words, but this is under-specification rather than conciseness — the sentence is too small to carry the definition's required information, so brevity does not earn credit here.

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

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

For a 5-parameter required-argument mutation tool with no annotations, no output schema, and no parameter descriptions, the description is completely inadequate. Nothing an agent needs in order to call this correctly is present.

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 5 required parameters (task_type, language, title, content, outcome) have 0% schema description coverage, and the description supplies no meaning for any of them. The agent cannot tell what format task_type or outcome should take, which is a critical gap for a write 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 essentially restates the tool name: 'ingest_exemplar' → 'Ingest a high-quality exemplar.' The qualifier 'high-quality' adds a small amount of meaning (only quality samples should be submitted), but the description never defines what an exemplar is or how it differs from the sibling tools ingest_procedure, knowledge_ingest_text, or retrieve_exemplars.

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

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

There is no when-to-use guidance at all: no indication of when to ingest an exemplar versus ingest_procedure or the knowledge_ingest_* family, no prerequisites, and no exclusions. The agent must infer the entire usage context from the tool name.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not say whether ingestion is idempotent, what happens if a procedure with the same name/version already exists, whether it overwrites existing content, or whether any permissions are required. 'Ingest' at least implies a write operation, which is the only behavioral signal present.

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 single sentence is not padded, but four words for a four-parameter mutation tool is under-specification rather than conciseness. There is no structure to front-load because there is effectively no content.

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 annotations, no output schema, and a 0%-coverage four-parameter schema, the description supplies none of the context an agent needs to call this tool correctly. Whatever behavior is expected of ingestion must be guessed.

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 four parameters (name, version, content, tags), and the description adds no meaning for any of them. It does not explain that 'version' is presumably a version identifier, that 'content' is the procedure body, or how 'tags' are used. With zero schema coverage, the description was required to compensate and does not.

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 verb and resource ('Ingest a new procedure'), so the general action is identifiable. However, 'ingest' is left undefined and there is no differentiation from the sibling tool ingest_exemplar, which also ingests content. It is the minimum viable statement of 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as ingest_exemplar, update_procedure_block, or knowledge_ingest_* tools. The agent must infer entirely from the name.

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?

No annotations exist, so the description carries the full burden. It does disclose the key trait — idempotency and only acting when the file is absent — which is meaningful. It omits what happens on no-op (return value, error vs success), what content gets written, and permission/overwrite implications.

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 the critical qualifier ('if missing') and the idempotency note front-loaded. Nothing is wasted, though the extreme terseness leaves room for one clarifying clause without bloat.

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

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

For a one-parameter initializer with no output schema and no annotations, the description covers the core action but leaves the caller guessing about the target path's semantics and the no-op outcome. Adequate but with clear gaps for a tool that writes to disk.

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% — project_root is documented only by minLength/maxLength constraints. The description never mentions the parameter, so it adds no meaning about whether it is an absolute filesystem path, a directory containing AGENTS.md, or how the path is resolved. With one undocumented parameter, the description should compensate but does not.

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 ('Initialize') and a specific artifact ('AGENTS.md'), which distinguishes it from the many other init_* siblings that operate on plans, tasks, or audits. It never names those siblings explicitly, so the differentiation is inferred from the resource name rather than spelled out.

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?

'if missing (idempotent)' implies the condition under which it acts and that repeated calls are safe, which is useful. However, it gives no guidance on when to prefer this over sibling tools like init_plan or manual file creation, nor any prerequisites.

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 no annotations, the description carries the full burden. It does disclose the key behavioral trait — idempotency, so no overwrite risk — but says nothing about what the created file contains, whether parent directories are created, or what the call returns on first vs. subsequent invocation.

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?

One short sentence, front-loaded with the action and the artifact. It is efficient but arguably too terse — the parenthetical is the only supporting detail and no room is given to scope or path semantics.

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 annotations, no output schema, and zero parameter documentation leave real gaps: the agent cannot determine what project_root expects, where the file lands, or what a successful response looks like. For a filesystem-mutating init tool, more disclosure is warranted.

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 single parameter project_root has no documented meaning anywhere. The description does not clarify whether it is an absolute path, a repo root, or a project identifier, nor how it relates to the AUDIT.md location.

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 (Initialize) and a specific artifact (AUDIT.md), with a condition (if missing). It is distinguishable from siblings like init_plan and init_agents by the target file, though it never says what an AUDIT.md is or contains.

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?

'if missing' implies the trigger condition and 'idempotent' signals it is safe to call when unsure. However, no alternatives or prerequisites are named — an agent cannot tell whether this should precede or follow init_plan/init_task, or whether it belongs in a bootstrap sequence.

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 no annotations, the description carries the full burden, and it does disclose the key behavioral trait: the operation is idempotent and will not clobber an existing PLAN.md ('if missing'). It omits other relevant behavior — whether a template/skeleton is written, whether a parent directory must exist, and whether anything is returned — which matters for a filesystem-writing tool with zero annotation coverage.

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 with no filler, and the condition ('if missing') and the safety guarantee ('idempotent') are both front-loaded. Every token 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 one-parameter initializer this covers what happens and the idempotence guarantee, but with no annotations, no output schema, and no parameter descriptions, the agent still cannot know what content lands in PLAN.md or how to confirm success. Adequate but with 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?

One parameter at 0% schema description coverage, so the description must compensate; it implies PLAN.md is scoped to the project, but never names project_root or explains that the file is created at that path. The parameter name is largely self-documenting, which keeps this from dropping further.

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 ('Initialize PLAN.md'), and the 'if missing' qualifier separates it from read_plan and update_plan_section, which operate on an existing plan. It does not explicitly name those siblings, but the create-vs-read-vs-edit distinction is clear enough to select correctly among the plan family.

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 '(idempotent)' note implies it is safe to call unconditionally before any plan work, which is a usable cue. However, it never states exclusions or alternatives — e.g., that update_plan_section should be used instead once PLAN.md exists, or how it relates to init_task/init_agents — so the agent must infer the surrounding 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?

With no annotations, the description does add two meaningful traits: it is idempotent and it does nothing when TASK.md already exists (so no overwrite risk). It stops short of describing what happens if project_root is invalid, whether directories are created, or what it returns.

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 waste. It is terse, though the brevity leaves holes that the other dimensions penalize.

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 file-mutating tool with no annotations, no output schema, and an undocumented required parameter. Given the density of init/task siblings, the description should clarify what file is created, where relative to project_root, and what is returned.

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 parameter project_root has 0% schema description coverage, so the description is the only place this could be explained, and it never mentions the parameter. The agent must guess whether project_root is a path, a name, or must already exist.

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

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

Names a specific verb and resource: 'Initialize TASK.md'. The 'if missing' qualifier makes the effect unambiguous, unlike the open-ended task_create siblings. It does not, however, distinguish itself from similar initializers such as init_plan, init_agents, or task_sync_md.

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?

'if missing (idempotent)' implies the call is safe at any point, but the description never states when to prefer this over task_create or init_plan, or what prerequisite the project_root must satisfy. Usage is only implicit.

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 no annotations, the description carries the full burden and does so well: consistent snapshot semantics, WAL safety, refusal to overwrite (so it will not clobber data), integrity reporting, and the out-of-band restore requirement all disclosed.

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

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

Three tight sentences; the core action and its safety guarantee are front-loaded, followed by the overwrite constraint and restore procedure, with no filler.

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

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

No output schema exists and the description says it 'reports its integrity' without hinting at the report's shape or where the snapshot lands by default beyond the schema's path field. Otherwise complete for a one-parameter tool whose safety behavior is fully explained.

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 the single optional target_path is fully documented there, including its default. The description adds nothing about path semantics, 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 (snapshot) plus resource (the store / SQLite file) and even names the mechanism (VACUUM INTO, WAL-safe), so an agent can distinguish it from knowledge_reindex or knowledge_delete_document immediately.

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 operational constraints that govern usage – it refuses to overwrite an existing file, and restore happens offline via 'cli restore <file>' with the server stopped. There is no competing backup sibling to route against and no explicit 'when to use' clause, but the constraints are concrete and 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?

With no annotations, the description carries the full burden. It does flag that chunks are deleted along with the parent document, which is useful cascade context, but it says nothing about permanence, recoverability, confirmation requirements, or behavior when the ID does not exist — all critical for a destructive 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?

One front-loaded sentence with no filler; the destructive verb and cascade scope come first. It is arguably too terse for a delete operation, but nothing in it is wasted.

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

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

For a destructive, zero-annotation tool with no output schema and undocumented parameters, the definition leaves out error/not-found behavior, irreversibility, and any effect on dependent indexes. An agent could invoke it correctly but has no visibility into consequences.

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% for the single parameter. 'By ID' only restates the param name doc_id and adds no format, source, or acquisition guidance (e.g. where to obtain the ID, or whether it matches knowledge_list_documents output), so the description 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?

Names a specific verb (delete), a specific resource (document) and the cascading scope ('all its chunks'), which is genuinely informative. It is clearly the destructive counterpart to knowledge_list_documents/knowledge_retrieve, but it never names a sibling or otherwise differentiates itself explicitly.

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 use this tool versus alternatives such as memory_forget or re-indexing, and no prerequisites or when-not-to-use guidance. The agent must infer everything about 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?

No annotations are provided, so the description carries the entire behavioral burden. Beyond the word 'statistics' hinting at a read-only aggregate, it says nothing about permissions, scope (all documents vs. a session), cost, or what dimensions are counted.

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

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

Three words with no filler, and the subject is front-loaded, so it is structurally clean. However, it is terse to the point of under-specification — brevity here comes from omitted information, not from tight writing.

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, no annotations, and no parameters, the description is the only source of information about this tool, and it does not say what statistics are returned or in what form. For a stats endpoint whose entire value is its return shape, this is insufficient.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description neither misleads nor needs to compensate for an under-documented schema.

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

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

The phrase 'Document storage statistics' names the resource (documents) and the kind of output (statistics), but supplies no verb and no scope. An agent can guess it is a read of aggregate document metrics, yet the description does not distinguish it from siblings like knowledge_list_documents, system_stats, or memory_stats.

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

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

There is no guidance on when to call this instead of knowledge_list_documents, system_stats, or memory_stats. The sibling set contains several stats-like tools, so the absence of any routing cue is a real gap rather than a minor omission.

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 no annotations, the description carries the full burden. It says 'supported source files' without listing what is supported, says 'recursively' as if it were fixed even though the schema exposes a recursive flag, and says nothing about re-ingesting already-indexed files, overwrite/dedup behavior, auth needs, or cost on large trees.

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 clause with no filler. However, the brevity is achieved partly by omitting necessary information rather than by trimming redundancy, so it stops 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?

For a mutation tool with no annotations, no output schema, and an un-annotated recursive parameter, the description leaves key questions unanswered: which extensions count as supported, what happens on re-ingest, and what the call returns. It is under-specified relative to the tool's complexity.

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

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

Schema coverage is 67%: path and extensions are documented in the schema, while recursive has no schema description beyond a default. The description's 'recursively' and 'supported source files' gesture at the recursive and extensions parameters but add no format details or defaults beyond what the schema already provides.

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 (ingest), modifier (recursively), and resource (supported source files from a directory). The word 'directory' implicitly separates it from knowledge_ingest_file and knowledge_ingest_text, but the description never names those siblings to make the routing 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?

No when-to-use guidance, no prerequisites, and no mention of the sibling ingest tools (knowledge_ingest_file, knowledge_ingest_text) that an agent must choose between. The agent is left to infer that a directory target selects 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that KB_ALLOWED_DIRS is honoured when set (a path-permission constraint), but says nothing about re-ingest behavior (overwrite vs. duplicate), indexing side effects, or whether the operation is reversible.

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 action front-loaded and the constraint second. Nothing is padded, though the brevity borders on under-specification for a tool with a nested parameter.

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 annotations, no output schema, and an undocumented nested metadata object, the description is too thin. It omits what metadata is for, what a successful ingest returns, and how it interacts with the other ingest variants.

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

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

Schema coverage is 50%: 'path' is documented in the schema while the nested 'metadata' object is undocumented in both the schema and the description. The description adds no parameter meaning whatsoever, leaving the metadata contract entirely unspecified.

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 compound verb and resource: 'Read a file and store it as a knowledge document,' which is clearly distinct from a text- or dir-based ingest. It does not, however, name the sibling tools (knowledge_ingest_text, knowledge_ingest_dir) it should be chosen over, so an agent must infer the distinction from the name 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 or when-not-to-use guidance and no alternatives are named, despite two close siblings (knowledge_ingest_text, knowledge_ingest_dir) that overlap heavily with this tool. The KB_ALLOWED_DIRS note is a constraint, not usage routing.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the processing pipeline ('chunked + embedded for later retrieval'), which is real value beyond the schema, but omits idempotency/dedup behavior, permissions, and what happens on re-ingest of the same title.

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 zero wasted words, and the parenthetical behavior note is packed efficiently. Terse rather than padded, though it sacrifices some detail for brevity.

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 annotations, no output schema, and half its parameters undocumented needs more than one sentence. Missing dedup/idempotency behavior, permission requirements, and metadata semantics leave an agent under-informed before calling 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 only 50%, and the two undocumented params (content, metadata) are the most consequential — content is required and metadata is a nested object. The description adds no meaning for any parameter, 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?

States a specific verb+resource (store raw text as a knowledge document) with a clear scope. 'Raw text' implicitly contrasts it with the file/dir ingestion siblings, though it never names them explicitly, so sibling differentiation is only implicit.

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 explicit when-to-use or when-not-to-use guidance. The 'raw text' phrasing hints that inline text is the input and file/dir siblings handle other sources, but the agent must infer the alternative rather than being routed to it.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses ordering (newest first) and that results are paginated, but says nothing about auth requirements, return shape, or total counts, leaving meaningful behavioral gaps for a no-annotation 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?

A single front-loaded sentence with zero filler; the core action leads and the qualifiers are compactly parenthesized. Every element 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-optional-parameter list tool with no output schema and full schema coverage, the description covers purpose, ordering, and pagination adequately. It is nearly complete, with only the non-differentiation from retrieval/search siblings as a residual gap.

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

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

Schema description coverage is 100%, so limit and offset are already documented in the schema. The description only echoes "paginated" without adding syntax, defaults, or boundary meaning beyond what the schema provides, matching the 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+resource ("List stored knowledge documents") and adds scope details (newest first, paginated). It does not explicitly distinguish itself from siblings like knowledge_search or knowledge_retrieve, which an agent could confuse it with, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives. An agent must infer that this enumerates documents rather than fetching specific ones, but nothing in the text routes it against knowledge_search/knowledge_retrieve/knowledge_document_stats.

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?

No annotations are provided, so the description carries the full load, and it delivers real operational traits: searches are blocked during the run, and re-running resumes after an interruption. It omits auth/permission requirements and expected runtime or cost, which would fully round out the behavioral picture.

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

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

Three tight sentences, front-loaded with the action and scoped by configuration. Each sentence adds distinct value: purpose, when-to-use/alternative, and operational side effects.

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-optional-parameter migration tool with no output schema, the description covers the trigger, the migration semantics, the blocking of searches, and resumability. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the single batch_size parameter is already fully documented ('lower uses less memory, higher is faster'). The description adds no parameter-level detail, 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 ('Re-embed') and resource ('every stored vector'), with the scope bound to the configured EMBEDDING_PROVIDER/MODEL. This clearly distinguishes it from the ingest siblings (knowledge_ingest_text/file/dir), which add content rather than migrate existing vectors.

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

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

Explicitly states the trigger condition ('after changing the embedding model or dimension') and names the alternative it replaces ('migrate the existing store in place instead of wiping and re-ingesting'). The agent knows both when to use it and what the competing strategy would be.

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 no annotations the description carries the full behavioral burden, and it does disclose the output shape (a context block ready for injection). However it says nothing about read-only nature, cost, latency, or result limits/ordering, leaving meaningful behavioral gaps for a 5-parameter retrieval 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?

Two tight sentences with no filler; the purpose leads and the routing guidance follows. 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 tool with no annotations, no output schema, and 40% schema coverage, the description conveys the core purpose and the return form but leaves behavioral and parameter details unaddressed. It is adequate to select the tool, not to invoke it confidently at the edges.

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

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

Schema description coverage is only 40%: query, top_k, and min_score are undocumented in the schema. The description adds no parameter-level meaning (no format, no default rationale, no interaction between doc_id/source and query), 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?

States a specific verb ("Retrieve") plus resource ("relevant context chunks") and even the output form ("ready-to-inject context block"). It explicitly differentiates itself from the sibling knowledge_search, so an agent can choose between them without opening either schema.

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

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

Gives an explicit selection rule: "Prefer this over knowledge_search when the result will be used as context." It names the alternative sibling and the condition that selects it. It stops short of an explicit when-not-to-use clause or any prerequisite/limit 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?

With no annotations provided, the description carries the full burden and does reasonably well: it discloses the default ranking strategy (Reciprocal Rank Fusion), the alternative scoring path, and that hits are returned as ranked chunks with scores. It stops short of permissions, failure modes, or pagination/result-size behavior, but the core behavioral mechanics are stated.

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?

Dense and front-loaded: purpose first, then return shape, then the two tuning knobs. Every sentence carries information, though the inline formula is slightly heavy for a description and could be tightened.

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

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

For a 7-parameter retrieval tool with no output schema and no annotations, the description covers the return format, the default ranking behavior, and the two most important tuning controls. The gaps (top_k, min_score semantics, sibling disambiguation) are moderate but the essential information an agent needs to call it correctly is present.

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 57%, so the description should compensate. It adds real meaning for alpha (the explicit blend formula) and explains is covered in both places, but top_k and min_score receive no semantics in either the schema or the description. That leaves two numeric tuning parameters undocumented, limiting the value 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 opens with a specific verb and resource: 'Hybrid semantic + keyword search over stored documents,' immediately telling an agent this is a retrieval tool combining two search modes. It is clear on its own, but it never distinguishes itself from close siblings like knowledge_retrieve or memory_recall, leaving sibling selection to inference.

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

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

It explains how to tune a search (explain for diagnosis, alpha for balance) but never states when to reach for this tool versus knowledge_retrieve, memory_recall, or retrieve_exemplars. There is no when-not-to-use guidance or prerequisite context, so routing among the many retrieval siblings rests entirely on the caller.

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 no annotations, the description carries the full behavioral burden. It discloses the ingestion target (searchable documents) and the auto-selection fallback behavior, which is useful. However, for a write/mutation tool it omits whether re-ingestion duplicates or overwrites documents, permission requirements, and failure behavior.

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

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

Two tight sentences with the primary action front-loaded and the fallback behavior second. No filler, though it could be marginally tighter.

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 description covers selection of the input source well, which is the main complexity. But with no annotations and no output schema, it leaves the mutation's side effects (dedup/idempotency, what is returned, error cases) unaddressed, so it is only adequate for a 3-parameter write 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: that directory is only meaningful when session_id is omitted and drives auto-picking. That interaction is not obvious from the individual property descriptions.

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: ingesting an opencode session's user inputs into the knowledge store as searchable documents. It distinguishes itself from generic ingest siblings by scoping to 'session user inputs', though it does not explicitly name those siblings (knowledge_ingest_text/file/dir).

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 clearly explains the two usage modes: pass a session id, or omit it and pass directory to auto-pick the most recent session. There is no explicit 'when-not' guidance or naming of alternative ingest tools, but the operational context is unambiguous.

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?

No annotations are supplied, so the description must carry the behavioral burden. It implies a read/list operation but does not state that it is read-only, what permissions or project state are required, what the 'auto-block versions' represent, or how failures are reported.

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

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

The description is a single short sentence and is front-loaded, but it is under-specified rather than genuinely concise. The unexplained 'auto-block versions' phrase makes the sentence less useful than its length suggests.

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 one-parameter listing tool, the description gives a high-level idea of the return contents, but with no output schema and no annotations it leaves both the parameter meaning and the result shape under-explained. It is barely minimum viable.

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 only parameter, project_root, has 0% schema description coverage, and the description never mentions it. It adds no meaning about what root path to provide, whether it must exist, or what format is expected.

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 uses the verb 'List' with the resources 'agent & skill files' and mentions 'auto-block versions', so the general enumeration purpose is visible. However, 'auto-block versions' is undefined and there is no explicit differentiation from related siblings such as provision_agent_skill or init_agents.

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

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

The description gives no guidance on when to use this tool versus provision_agent_skill, init_agents, or procedure-related tools. It also omits prerequisites, exclusions, or expected context for the listing operation.

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?

No annotations are provided, so the description carries the full burden. 'List' implies a read operation, but the description does not disclose whether it requires permissions, paginates results, or what the returned data contains.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a zero-parameter list tool, though it omits useful context rather than adding unnecessary text.

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 simple zero-parameter schema, the description is minimally sufficient: an agent knows how to invoke it. However, with no output schema or annotations, it should probably say what 'list' returns (names, IDs, full procedure bodies) to be fully 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?

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for zero parameters is 4, and the description does not need to compensate for schema gaps.

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

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

The description states a specific verb and resource: 'List all procedures.' It is clear what the tool does and its scope ('all'), but it does not explicitly differentiate from siblings like get_procedure or ingest_procedure.

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 guidance is given about when to use this tool versus alternatives such as get_procedure. It also does not mention prerequisites, filtering, or whether this is the right choice for enumerating procedures.

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?

No annotations exist, so the description carries the full burden. It usefully discloses that real compilers/checkers are executed and that output is location-aware, but omits whether the operation is read-only, whether the toolchains must be installed, expected latency, and what happens when nothing is found.

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

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

A single front-loaded sentence with no filler; the concrete tool names do real work. It is however sparse for a tool with an undocumented parameter, so brevity shades into under-specification.

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 and no annotations, so the description must cover both safety and returns. It sketches the return shape ("structured, location-aware issues") but leaves the sole parameter and failure/empty-result behavior unexplained, which is insufficient for an execution-backed diagnostic 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?

There is one parameter, project_root, at 0% schema description coverage, and the description never mentions it — no default (cwd?), no meaning of the path, no constraint. The single ambiguity an agent must resolve is left 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?

Specific verb+resource ("Run language-server-style diagnostics") with concrete implementation examples (tsc/pyright/cargo check/go vet) and a stated return shape ("structured, location-aware issues"). It does not differentiate from any sibling, though run_verification is the nearest potential confusion and no contrast is offered.

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 never says when to call this versus alternatives such as run_verification or self_critique, nor any precondition (e.g. run after edits, before commit). Usage must be entirely inferred from the tool name.

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 no annotations, the description carries the full behavioral burden, and it does disclose one non-obvious trait: pruning is opt-in and off by default via an environment variable. However, it never says whether dedup merges or deletes records, whether the operation is reversible, or whether the score boosts are persistent mutations.

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-loads the two default behaviors and defers the opt-in destructive one to a parenthetical. No filler, no restatement of the tool name.

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 maintenance mutation with no annotations and no output schema, the description covers what happens but not the surrounding context an agent needs: expected frequency, safety/reversibility, or what the operation reports back. Adequate but with 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 tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description does add one quasi-parameter detail by naming the KB_PRUNE environment variable that toggles the prune behavior.

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 three specific operations on a specific resource: deduplicating near-identical memories, boosting frequently-used ones, and pruning stale ones. That is a concrete verb+resource statement that separates it from siblings like memory_remember, memory_recall, and memory_forget.

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 only conditional given is operational ('enable with env KB_PRUNE=1'), which tells the agent when pruning happens but not when to invoke consolidation at all. There is no guidance on triggers (e.g., after bulk ingest, periodically) or when to prefer memory_forget for targeted deletion 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?

With no annotations, the description carries the full burden. It discloses the interesting behavioral trait that the output is a synthesized, compact block rather than raw records, which is genuinely useful. However it omits that this is a read-only/non-mutating operation, how relevance is ranked, and any size or token bounds.

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

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

Two short sentences with the core action front-loaded and zero filler. Efficient, though the brevity comes at the cost of detail elsewhere.

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 read tool with no output schema, the description covers what the tool produces at a high level. It is minimally adequate, but for a 0%-coverage schema it should have explained top_k and the compactness/ranking 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 0%, so the description must compensate and largely does not. It names 'topic' only implicitly by mentioning 'a given topic' and never addresses top_k, its default of 6, or its 1-20 range, leaving the result-count control entirely 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 and resource: 'Build a compact context block from the most relevant memories for a given topic.' This distinguishes it from memory_recall (retrieval of items) and memory_list (enumeration), though it never names those siblings explicitly.

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?

'Best for injecting memory into prompts' gives one positive usage context, but there is no guidance on when to prefer this over memory_recall or memory_search, no prerequisites, and no exclusions. Usage is implied rather than specified.

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 no annotations, the description carries the full behavioral burden, and for a deletion tool it omits the most important facts: whether the delete is permanent or soft, whether it is reversible, and what happens if the ID does not exist. 'Delete' implies destruction, but nothing confirms irreversibility.

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 zero filler. It is efficiently written, though arguably too terse for a destructive operation where a little more text would earn 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 mutation tool with no annotations, no output schema, and no parameter documentation, the definition is incomplete: an agent cannot tell whether the operation is recoverable, what the response contains, or how to recover from a bad ID.

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 supply the meaning of the single parameter. 'By ID' does establish that the string identifies a memory, which is the essential semantic, but it gives no format, no hint about where to obtain the ID, and no error behavior for an invalid 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 specific verb ('Delete') and resource ('a memory') plus the identifying key ('by ID'), which cleanly separates it from memory_update, memory_get, and memory_consolidate. It stops short of explicitly naming a sibling it is not, but the action is unambiguous.

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

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

There is no guidance on when to use this versus memory_update (to change content), memory_consolidate (to merge), or memory_list/memory_recall (to locate the correct ID first). No prerequisites or exclusions are given.

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?

No annotations are provided, so the description carries the entire behavioral burden, and it discloses almost nothing: no error/miss behavior for an unknown ID, no note on whether forgotten or consolidated memories are still retrievable, and no permission or scope constraints. The read-only nature is only weakly implied by 'Get'.

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 the resource and the lookup key front-loaded and zero filler. It is appropriately sized given the simplicity of the tool, though brevity shades into under-specification rather than efficiency.

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 lookup with no output schema, the essentials (what it does, what key it takes) are covered. What is missing is the failure mode for a nonexistent ID and any hint about the returned memory shape, which matters since there is no output schema to fall back on.

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 parameter has 0% schema description coverage, so the schema contributes no semantics at all. The description's 'by ID' does tell the agent that the id argument is a memory identifier rather than, say, a task or document ID, which is a real but minimal compensation.

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 (get) and resource (memory) with a scope qualifier ('single', 'by ID'), which is enough to distinguish it from memory_list and memory_recall. It stops short of naming those siblings explicitly, so differentiation is only implied rather than declared.

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?

'By ID' hints that a known identifier is a precondition, but there is no statement of when to choose this over memory_recall, memory_list, or memory_context. An agent must infer the selection rule from sibling names alone.

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?

No annotations are provided, so the description carries the full behavioral burden. It only implies read-only semantics via 'List' and says nothing about result ordering, pagination/limit behavior, whether results are truncated, or what the response looks like.

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 well-formed sentence with the resource and all filter dimensions front-loaded and no wasted words. Its brevity is appropriate for a list tool, though it leaves little room for the usage context an agent would want.

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 4-parameter tool with no annotations, no output schema, and 0% schema coverage, the description should explain return shape, ordering, and the limit parameter. None of that is present, so an agent must guess at result semantics.

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 compensate. It names three of four parameters (type, tag, min_importance) but omits 'limit', its default of 100 and cap of 500, and the enum's seven memory types, leaving meaningful gaps.

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

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

The description gives a specific verb+resource ('List memories') and names the three filter dimensions, so an agent can distinguish it from point-access siblings like memory_get or memory_recall. It stops short of explicitly contrasting with those siblings, so it does not reach 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?

'optionally filtered' implies when the filters apply, and enumerating the filter dimensions gives an implicit usage cue. However, there is no explicit when-to-use versus memory_recall, memory_get, or memory_context, and no exclusions or ordering 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?

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only operation, how results are ranked or capped (top_k max 30), what min_score filters, or whether recall touches persistent state. Only the bare 'search' semantics are conveyed.

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

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

Two short sentences with the core operation front-loaded and no wasted clauses. The second sentence is a little fluffy but functions as usage framing rather than 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 annotations, no output schema, and three entirely undocumented parameters, the description leaves too much to inference for a search tool. It never describes the shape of a returned memory or how scores are surfaced to the caller.

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% for all three parameters, so nothing documents that top_k is the result count or that min_score is a similarity threshold. The phrase 'relevant to a query' hints at a relevance cutoff but never explains min_score's scale or how it interacts with top_k.

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: semantic search over long-term memories. That distinguishes it from keyed siblings like memory_get and memory_list, but it never names those alternatives, so the differentiation is implicit 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?

"This is how you remember past context" implies the recall use case, which is genuine guidance about when to reach for it. However, it offers no exclusions and does not distinguish it from memory_context, knowledge_search, or retrieve_exemplars, all of which an agent might plausibly pick 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?

No annotations are supplied, so the description carries the full behavioral burden. It conveys cross-session durability, but says nothing about whether writes dedupe, overwrite, return an identifier, or require any prerequisites for a store operation with no output schema.

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

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

Two tight sentences with the action verb front-loaded and no filler. The parenthetical type list mildly duplicates the schema enum but remains readable.

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 4-parameter write with no annotations and no output schema, the description omits what a caller gets back and how to later reference the stored memory via siblings (memory_get/memory_update). An agent lacks enough to fully close the loop after storing.

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 75% and the schema itself documents content, tags, and importance. The description only restates the type enum (fact, decision, etc.), adding no syntax or format detail beyond the structured fields, which matches the baseline for moderate coverage.

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 ('Store') and resource ('long-term memory') and enumerates the memory types, which is more than a tautology. It does not explicitly distinguish itself from siblings like memory_update or memory_consolidate, so it falls short of a 5.

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

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

'Use this to persist things that should be remembered across sessions' gives a clear when-to-use context, but there are no exclusions or alternatives named (e.g. memory_update for edits, memory_consolidate for merging). Usage is implied rather than 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?

No annotations are provided, so the description must carry the full behavioral burden. 'Statistics' implies a read-only operation, but the description never states side effects, auth requirements, or that it is non-mutating; the returned metrics are output content, not a behavioral disclosure.

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 noun phrase with a parenthetical metric list. No sentence is wasted and the core purpose appears first.

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 stats tool with no output schema, naming the returned metrics is sufficient to invoke it correctly. The only modest gap is the absence of a read-only assurance and any sibling-routing 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?

Zero parameters, so there is no parameter semantics for the description to add or omit. The baseline for a no-param tool 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: 'statistics' for 'long-term memory', and lists the metrics returned (count, tokens, importance, by type). It is generally distinguishable from siblings like memory_list and system_stats, but does not explicitly position itself against 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?

No when-to-use guidance, no alternatives, and no exclusions. The description is a label of contents rather than an invocation guide, leaving the agent to infer when memory_stats is preferable to memory_list, memory_recall, or system_stats.

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 no annotations, the description carries the full behavioral burden and falls well short. It doesn't say whether the update is partial (only id is required, implying omitted fields are left alone) or a full overwrite, what happens if the id is unknown, or whether a changed importance/type has side effects. Only mutation intent is conveyed.

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 tight sentence with the resource stated up front and zero filler. It is efficient, though its brevity contributes to the gaps noted in other dimensions.

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 annotations and no output schema needs the description to explain partial-update behavior, not-found handling, and the effect of the update; none of that is present. The field enumeration helps somewhat but leaves the agent guessing about core mutation semantics.

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 compensate, and it does list four of the five parameters (content, type, importance, tags). However it adds no meaning beyond the property names already visible in the schema — no format, scale, or tag-replacement semantics — and id is only implied by 'existing memory'.

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+resource (update an existing memory) with the updatable fields named, so it is clearly distinguished from memory_remember (create), memory_get/recall (read), and memory_forget (delete). It stops short of explicitly naming those alternatives, which is what a 5 would require.

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 routing to siblings. The word 'existing' weakly implies the id must already exist, but nothing tells the agent to use memory_remember instead when the memory doesn't exist yet.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing: not whether it invokes an LLM (latency/cost), whether it persists state, what it returns, or any side effects. For a tool named 'model_decision' that may make a model routing choice, this opacity is a serious gap.

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 short and front-loaded, but this is under-specification rather than conciseness; the fragment is too compressed to convey meaning, and the colon-separated field list is not self-explanatory.

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 annotations, no output schema, no enum hints, and zero parameter documentation, the description leaves everything an agent would need — purpose, when to use it, argument meaning, and the shape of the result — unspecified.

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?

Four parameters (task, files, model, project_root) with 0% schema description coverage, and the description mentions none of them and adds no meaning. The agent must guess what 'files' and 'model' do — filter candidates, override the choice, or supply context.

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 'Internal model decision: tier/risk/route/needsVerify' restates the tool name and lists possible output fields rather than stating a verb and resource. It never says what the tool actually does (classify a task? pick a model? produce a routing decision?), and it does not distinguish itself from the sibling decision_classify or detect_model.

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

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

There is no guidance on when to call this versus decision_classify, detect_model, get_model_profile, or self_critique. The single word 'Internal' weakly implies it is not meant for direct user invocation but gives no condition, prerequisite, or alternative.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses two useful traits (idempotent, append mode), but omits what is overwritten, whether the operation is destructive, permission requirements, and what the result looks like — significant gaps for a write 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?

A single short sentence with the key action and mode front-loaded and no filler. It is efficiently sized, though arguably too terse to be fully useful.

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 mutation tool with no annotations, no output schema, and zero parameter documentation, the description is not complete enough to call the tool confidently. The idempotency note helps but does not compensate for the missing parameter and behavioral detail.

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 mentions neither parameter. The opaque force_version parameter is left entirely unexplained in both the schema and the description, so an agent cannot infer its format or effect.

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 gives a verb pair (provision/append) and a resource (agent & skill files), so the core action is legible. However, it does not distinguish this tool from closely related siblings such as init_agents, init_audit, or bootstrap_session, leaving the agent to guess which file-provisioning tool is appropriate.

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 prerequisites, and no mention of alternatives among the many init_/bootstrap_ siblings. The agent gets a purpose but no routing signal for choosing this tool over them.

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?

No annotations, so the description carries the full behavioral burden, yet it only says 'read content'. It does not disclose what happens if PLAN.md is missing, whether the default `full=true` returns the entire file versus a summary, or any output format details.

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

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

Extremely short and front-loaded with zero filler, but the brevity comes at the cost of under-specification rather than economy; one more clause on `full` would have been worth the words.

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

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

For a two-parameter tool with no annotations, no output schema, and 0% schema coverage, the description should at minimum explain `full` and the missing-file case. As written, an agent must guess at half the invocation surface.

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 mentions neither parameter. In particular `full` (default true) is completely unexplained — an agent cannot tell that setting it false yields partial content — and `project_root` is undocumented in both schema and description.

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: read PLAN.md content. An agent knows exactly what artifact this returns. It does not differentiate from siblings like init_plan or update_plan_section, 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?

No guidance on when to call this rather than init_plan, update_plan_section, or task_from_plan, and no preconditions stated (e.g., does PLAN.md need to exist first?). The agent must infer usage from the name alone.

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?

No annotations are provided, so the description carries the full burden. It does not disclose how 'best' is determined (ranking/scoring), whether results are read-only safe, what is returned, or any limits beyond what the schema implies.

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 efficient sentence with the key concept front-loaded and no wasted words. Brevity here is appropriate, though it edges toward under-specification rather than true 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 3-parameter tool with zero schema descriptions, no annotations, and no output schema, the description does far too little. An agent lacks ranking semantics, result shape, and top_k meaning needed to call it reliably.

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 should compensate. It only loosely maps 'task' as the query and 'task_type' as an optional filter, and never mentions top_k at all, leaving a third of the parameters undocumented anywhere.

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 (Retrieve) and resource (exemplars) with the additional qualifier 'best' and the optional task_type filter. An agent can tell it apart from ingest_exemplar, though it does not name or distinguish itself from near-neighbors like get_procedure or knowledge_retrieve.

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?

Implies usage via 'for a task' and notes that task_type is an optional filter, but gives no when-to-use/when-not guidance and no direction on choosing between this and related retrieval siblings. The alternative selection is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. 'Allowlisted' hints at a security restriction but leaves key traits undisclosed: what happens when a command is not allowlisted, whether commands run sequentially or in parallel, mutation/execution risk, or the effect of cwd and timeout_ms.

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 tight sentence with the scope-defining examples placed up front and no wasted words. It is arguably terse to the point of under-specification, but structurally it is clean and front-loaded.

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 command-execution tool with no annotations, no output schema, and zero documented parameters, the definition is too thin. An agent lacks the operator/allowlist rules, return shape, and per-parameter semantics needed to invoke 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 three parameters (cwd, commands, timeout_ms), and the description mentions none of them. The names are largely self-explanatory, but nothing explains the accepted command vocabulary, the allowlist behavior, or timeout semantics 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 gives a specific verb (Run) and resource (verification commands), and the parenthetical 'test/lint/typecheck' pins down the scope precisely. No sibling tool overlaps with local verification, so sibling differentiation is not a concern, but the definition itself is clear and concrete.

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 never states when to run verification, what 'allowlisted' permits, or any prerequisites (e.g., that a project must exist in cwd). An agent must infer usage from the name alone, with no exclusions or alternative-tool routing given.

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?

No annotations are provided, so the description carries the full burden. It says nothing about what a "score" is (numeric, percentage, pass/fail), what compliance criteria are applied, whether the operation is read-only, or what the result looks like.

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 extreme brevity reflects under-specification rather than disciplined concision.

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 annotations and no output schema, the description should explain the return form and scoring semantics, but it does not. Nothing tells the agent what to expect back or how strictly to format the plan input.

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

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

There is one parameter named "plan" with 0% schema description coverage, self-descriptive by name. The description adds "plan/diff," hinting at acceptable input, but this is ambiguous since the schema only accepts a single "plan" string.

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 ("score") and resource ("procedure compliance of a plan/diff"), so the agent knows what it does. It does not differentiate itself from plausible siblings such as run_verification or get_procedure, which is the main gap.

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

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

There is no guidance on when to use this tool versus alternatives like run_verification, nor any preconditions or exclusions. The agent must infer usage entirely from the tool name.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the tool works 'without LLM' and names output components, but it does not explain how scoring is performed, what severity thresholds mean, whether the artifact is modified, or what the result format looks like.

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

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

The description is a single compact sentence with no wasted language and is front-loaded with the core purpose. However, its extreme terseness contributes to the missing usage and parameter details.

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 that there are no annotations, no output schema, and 0% schema description coverage, the description is too sparse for a tool with a non-trivial scoring and verdict model. It names the artifact and tier parameters nowhere, leaving the agent unable to confidently call the 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%, and the description does not mention either parameter. The meaning of 'artifact' is only weakly implied, and the role of the 'tier' enum (weak/medium/strong) is not explained 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?

The description clearly states that the tool produces a structured self-critique with weighted checklist, scoring, severity, and verdict, and that it operates without an LLM. This is more specific than the bare tool name, but it does not distinguish the tool from related siblings such as score_compliance or run_verification.

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

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

The description gives no explicit guidance on when to use this tool, when not to use it, or which sibling tools are alternatives. An agent must infer usage from the phrase 'self-critique' alone.

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?

No annotations are provided, so the description carries the full burden. It does disclose two real behavioral traits: the change is session-scoped and is an 'env-level hint' rather than a hard configuration mutation. However, it says nothing about permissions, persistence, reversibility, or effect on concurrently running tools, which matters for a state-changing call.

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 the action and scope stated first and no filler. The parenthetical is useful but left vague rather than expanded, so it is efficient without being fully crisp.

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 state-changing tool with no annotations, no output schema, and a completely undocumented parameter, this is too thin. An agent cannot tell valid model values, whether the override persists past the session, or what feedback (if any) confirms the change took effect.

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

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

Schema coverage is 0% for the single required 'model' parameter, so the schema supplies no format guidance. The description only implies the parameter is the model to override; it never states accepted identifier syntax (provider prefix, aliases, case) or failure behavior for unknown models.

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 (override) and resource (the model for this session), so an agent can distinguish it from sibling reads like detect_model or get_model_profile. The parenthetical 'env-level hint' slightly muddies whether an actual switch occurs, but the core action is identifiable.

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 'for this session' implies a scoping condition, but the description never says when to prefer this over detect_model, get_model_profile, or model_decision, nor whether it must be called before other tools. No when-not guidance at all.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' plus 'stats' clearly implies a non-mutating read, and the description usefully enumerates the returned fields, but it does not state permissions, cost, or whether the call has side effects. Adequate but not rich.

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

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

A single front-loaded sentence with zero filler; the verb and resource lead, followed by a compact colon-delimited inventory of what is reported. Nothing could be removed without losing information.

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

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

For a parameterless read-only stats tool with no output schema, the description supplies the essential missing piece — a list of the metric categories returned. No return-shape or formatting details are given, but for a summary endpoint this is close to sufficient.

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

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

The tool takes zero parameters, so per the baseline there is no parameter semantics to document. The description correctly avoids inventing parameters and instead spends its words on what the tool returns.

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 (Get) and resource (overall system stats), then enumerates the exact contents: DB location, documents, chunks, memories, tokens, embedding backend. The word 'overall' distinguishes it in scope from narrower siblings like memory_stats or knowledge_document_stats, though those siblings are never named explicitly.

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 only implied by the scope word 'overall' — an agent can infer this is the broad, cross-subsystem health/summary call rather than a targeted one. There is no explicit when-to-use statement and no guidance on when memory_stats or knowledge_document_stats would be preferred 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?

With no annotations, the description carries the full behavioral burden, and it only says a status is set. It omits whether this is reversible, whether prior status matters, whether the reason is persisted or surfaced later, and what the call returns 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?

A single efficient sentence with the action front-loaded and no filler. Its brevity is appropriate, though it leans toward under-specification rather than crispness.

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 state-mutating tool with no annotations, no output schema, and undocumented parameters needs more: prerequisites, reversibility, and response shape are all absent. As written an agent cannot call it confidently beyond guessing.

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% for both parameters. The description hints that 'reason' is a free-text justification, but 'id' is never explained (task id from task_create/task_get?) and no format or constraint guidance is added beyond the schema.

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

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

States a specific verb ('Set') plus resource ('task status') and the resulting state ('blocked'), with the reason parameter named. An agent can distinguish it from task_start/task_done by the target status, though no sibling is named explicitly.

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: it doesn't say whether the task must already be started, whether blocking replaces task_done, or when blocked is preferable to just leaving the task open. Usage must be inferred entirely from the name.

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?

No annotations are provided, so the description carries the full behavioral burden for a mutating tool, yet it discloses nothing: no required fields, no side effects, no persistence/linking behavior for plan_ref, no permission needs. This is a bare minimum statement with zero behavioral context.

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

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

It is short and front-loaded, but that brevity reflects under-specification rather than efficient concision. A single four-word sentence cannot earn its place for a 4-parameter mutation tool.

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

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

With 4 parameters, no annotations, no output schema, and 0% schema description coverage, the definition leaves critical information entirely absent. An agent has no basis to call this tool correctly beyond guessing field semantics.

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 4 parameters (owner, title, plan_ref, priority), and the description adds no meaning for any of them. An agent cannot tell what plan_ref links to or how priority is interpreted without reading raw schema types.

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 verb and resource ('Create a new task'), but it essentially restates the tool name 'task_create' and gives no scope, distinctions, or qualifiers. It is especially ambiguous against siblings like init_task, task_list, and task_get, which an agent must be able to tell apart without opening 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?

There is no guidance on when to use this tool versus init_task or task_sync_md, no prerequisites, and no conditions. The agent must infer everything from the tool name alone.

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?

No annotations are provided, so the description carries the full disclosure burden and largely fails it. It implies a destructive mutation but says nothing about reversibility, whether subtasks or linked records are cascaded, or what permissions are required. Only the barest signal (this is a delete) is conveyed.

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 single sentence is front-loaded and free of waste, which is appropriate in size. But brevity here shades into under-specification rather than discipline, since nothing beyond the verb+resource is offered for a destructive operation.

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

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

For a destructive tool with no annotations, no output schema, and an undocumented parameter, the description is too thin. An agent cannot determine consequences of the call (permanent removal, cascade behaviour, error conditions), which is the minimum needed before invoking a delete.

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 input schema has 0% description coverage for the single required 'id' parameter, and the description does not compensate by explaining the identifier's expected form or source. The agent must infer that 'id' is a task identifier, which is plausible but unstated.

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 ('Delete a task'), so the core operation is unambiguous. However, it offers no differentiation from the many sibling task tools (task_done, task_block, task_create), so an agent cannot tell from the text whether deletion is the same as marking done or a distinct destructive action.

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 mention of prerequisites, and no routing to alternatives such as task_done/task_block for soft state changes. The agent gets only the operation name, not the conditions under which it should be preferred over the rest of the task lifecycle family.

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 no annotations, the description must carry behavioral disclosure, but it only states the mutation. It omits idempotency, required task state, permissions, side effects, and whether the change is reversible.

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?

One short sentence, front-loaded and free of filler. However, it is so minimal that it borders on under-specification for a state-transition tool.

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

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

For a mutation tool with no annotations or output schema, the description is incomplete. It should at least state what happens on success/failure and any prerequisite task state.

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

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

Schema coverage is 0% and the single id parameter has no description in the schema. The description does not identify or explain the id, so it adds no meaning beyond the parameter name.

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 ('Set task status to done'), making the mutation target clear. It does not differentiate from sibling status-transition tools like task_start or task_block, but the action itself 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?

Provides no when-to-use guidance, prerequisites, or alternatives. It does not say when a task should be marked done versus blocked or deleted, leaving the agent to infer.

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 no annotations, the description bears full behavioral burden for what is evidently a write operation. It does not say whether existing tasks are duplicated, overwritten, or skipped, whether it is idempotent, what happens if PLAN.md is missing or malformed, or what gets returned.

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?

One short sentence with the action front-loaded; nothing is padded. Brevity here costs nothing structurally, though it reflects under-specification rather than efficient completeness.

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 annotations, no output schema, and an undocumented parameter needs far more than one sentence. Missing are idempotency/duplication semantics, PLAN.md path assumptions, error behavior, and result shape.

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

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

Schema coverage is 0% and the single parameter, project_root, is never mentioned in the description. Its name implies a directory path, but the description adds no clarification about its expected form or relationship to the PLAN.md being parsed.

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 (auto-generate) and resource (tasks) plus the source (PLAN.md step/bullet lines), which distinguishes it from generic sibling creators like task_create or init_task. It could be even sharper about what counts as a 'step/bullet line', but the core purpose is 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?

No indication of when to use this versus task_create, init_task, read_plan, or task_sync_md, nor prerequisites such as an existing PLAN.md. The agent must infer the ordering of these plan/task tools entirely from the name.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the bare operation: no error/not-found behavior, no statement that the call is a side-effect-free read, and no indication of what is returned. 'Get' weakly implies read-only, but that is inference, not disclosure.

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

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

Three words, front-loaded with the verb and no filler or repetition of the title. It is appropriately terse for a trivial lookup, though the terseness shades into under-specification.

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 single-parameter lookup with no nested schema this is close to sufficient, but with no output schema and no annotations the description should at least sketch the not-found/error behavior or the shape of the returned task. As written, the agent must call it blind.

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 compensate; it only tells us the lookup is 'by id', which matches the single obvious `id` parameter without adding format, example, or constraint detail. It confirms the parameter's role but adds nearly nothing beyond the schema's property name.

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?

'Get task by id' states a specific verb (get) and resource (task) plus the retrieval key, which cleanly separates it from list/create/delete siblings. It stops short of explicitly naming which sibling to use instead, but the resource+key combination 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?

The description gives no guidance on when to use this versus task_list or the other task tools, and states no preconditions (e.g. what happens if the id is unknown). For a one-line retrieval tool this is a predictable gap rather than a misleading statement.

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

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

No annotations are provided, so the description carries the full burden. It implies a read operation and discloses that results are paginated, but says nothing about ordering, default limit, total-count behavior, or permissions. For an unannotated query tool that is a thin disclosure.

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?

One sentence, front-loaded with the verb and scope, with zero padding. It is tight; the only critique is that the brevity is achieved partly by omitting information elsewhere.

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 4-parameter list tool with no annotations and no output schema needs the description to describe the return shape and parameter constraints. Neither is present, so an agent cannot predict result ordering, item shape, or valid filter values.

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

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

Schema coverage is 0% across 4 parameters, so the description must compensate and largely does not. It correctly frames status/priority as filters and pagination as limit/offset, but gives no accepted status values (no enum exists), no priority range, and no default limit, leaving the agent to guess valid inputs.

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+resource ("List tasks") with the filter fields and pagination named, so the operation is unambiguous. It does not, however, distinguish itself from siblings like task_get or task_summary that an agent might mistake for listing/aggregation.

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?

"Optionally filtered by status/priority" implies when the filters apply, but there is no explicit guidance on when to reach for task_list versus task_get, task_summary, or task_from_plan. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden, and it only discloses the resulting status value. It says nothing about idempotency (calling on an already-doing task), side effects such as markdown sync (task_sync_md exists as a sibling), failure behavior for unknown ids, or permissions.

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 the action and target state front-loaded, no filler or repetition. It is efficient, though the brevity reflects under-specification rather than disciplined trimming.

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 no annotations, so the description must explain what a call returns and what happens on error, and it does neither. For a mutation tool in a family of task lifecycle tools, the agent lacks enough to invoke 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% and the description adds no meaning to the single 'id' parameter beyond what the tool name implies. It never states that id is a task identifier or what form it takes (UUID, slug, numeric), leaving the parameter 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?

The description names a specific verb (set) and the exact resulting state ("doing") on a task resource, which distinguishes it from siblings like task_done or task_block by implication. It does not explicitly name or contrast those siblings, so it falls short of a 5.

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

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

There is no guidance on when to call this versus task_done, task_block, task_create, or init_task, and no mention of preconditions such as the task already existing or already being in progress. The agent must infer the usage entirely from the tool name.

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 no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not state that this is a read-only aggregate, what dimensions are summarized (counts by status? per-task rollup?), or whether it covers all tasks or just the current session. For a zero-annotation tool this is a significant disclosure gap.

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?

One short, front-loaded fragment with no wasted words, but it is terse to the point of under-specification rather than genuinely concise. It is efficient but does not earn its brevity by conveying useful content.

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

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

For a zero-parameter, no-output-schema aggregate tool, the description should define the shape of the summary (what statuses, what scope, what counts). None of that is present, leaving the agent unable to predict 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?

The schema has zero parameters, so there is nothing to document; per the baseline rule a 4 applies. The description neither helps nor hurts here.

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 'Summary of task statuses' essentially restates the tool name (task_summary) in slightly expanded form, with no verb and no indication of what the summary contains or how it differs from task_list or cognitive_status. It names the resource (task statuses) but not the action, making it a near-tautology rather than a differentiating statement.

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

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

There is no guidance on when to call this instead of task_list, task_get, or cognitive_status, nor any mention of prerequisites or context. The agent must guess from the name alone.

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 no annotations, the description carries the full behavioral burden, but it only says 'Sync TASK.md from DB.' It does not disclose whether existing TASK.md content is overwritten, whether the file is created if missing, what happens on DB errors, or whether the operation is reversible.

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

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

The description is a single front-loaded sentence with no wasted words. It is perhaps overly terse for a mutating sync operation, but structurally it is efficient and direct.

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 file-writing sync tool with no annotations, no output schema, and an undocumented parameter, the description is not complete enough. An agent still lacks key details about side effects, overwrite behavior, and how project_root is used.

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

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

There is one required parameter, project_root, with 0% schema description coverage. The description does not mention it or explain how it identifies the project directory whose TASK.md is synced, so it fails to compensate for the missing schema documentation.

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

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

The description states a specific verb ('Sync') and resource ('TASK.md'), plus the source ('from DB'), so an agent can infer it regenerates TASK.md from database state. It does not differentiate from siblings, but no sibling performs this exact file-sync 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?

The description gives no guidance on when to use this tool, when not to, or what alternatives exist. It does not mention prerequisites such as needing an initialized project or existing DB records.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses almost nothing: not whether this is a partial or full replace, not what happens to omitted fields, not whether the id must already exist, not required permissions or reversibility. Only the implicit notion of mutation is conveyed.

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 short and front-loaded with no filler, but the brevity comes from under-specification rather than efficiency. A single fragment is not enough structure for a six-parameter mutation tool.

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

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

Six parameters with zero schema descriptions, no annotations, and no output schema means the description is the only source of semantics, and it omits almost everything an agent needs. Return values and error behavior are entirely undocumented.

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 compensate, and it only lists field names already visible in the schema. It adds no meaning for priority (allowed range/scale), plan_ref (format or referent), owner (identifier format), or the required id, and never states that unspecified fields are left unchanged.

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

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

Names a verb (Update) and resource (task) and enumerates the mutable fields, so the basic purpose is inferable. But it's a telegraphic fragment with no statement of what 'update' means here and no differentiation from mutating siblings like task_start, task_done, task_block, or task_sync_md.

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

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

There is no guidance on when to use this versus task_start/task_done/task_block for state transitions, or task_sync_md/task_from_plan for other kinds of task mutation. The caller is left to infer that this tool edits descriptive fields only.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it only implies mutation. It does not say whether the section must already exist, what happens if the heading is absent, whether the rest of the file is preserved, or whether the file is created on demand.

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 wasted words, and the key mechanism is front-loaded. However, the brevity reads as under-specification rather than disciplined concision given the missing behavioral and parameter 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?

A three-parameter file-mutating tool with no annotations, no output schema, and no parameter descriptions needs far more than one sentence. An agent cannot tell from this whether a missing heading is an error, whether the file is created, or what the tool returns.

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 all three required parameters, so the description must compensate. 'By heading' usefully clarifies that the heading parameter identifies the target section, but project_root and content receive no explanation at all (e.g., is content markdown replacing the whole section or appended?).

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 (Update) and resource (a PLAN.md section), and adds the targeting mechanism ('by heading'), so an agent knows exactly what the operation acts on. It does not, however, differentiate itself from adjacent plan-related siblings such as read_plan, init_plan, or task_sync_md.

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

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

There is no guidance on when to use this versus read_plan, init_plan, or task_sync_md, and no stated preconditions (must PLAN.md already exist?). Usage is only implied by the name and the word 'Update'.

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 no annotations, the description carries the full burden for what is evidently a file-mutating operation, and it says almost nothing: not which files get rewritten, whether existing content outside the auto block is preserved, whether the update is idempotent or destructive, or what failures look like. 'Update ... with a new version' is the only behavioral fact 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?

A single front-loaded sentence with no wasted words, but the terseness is under-specification rather than efficiency. Nothing is repeated, but nothing is expanded either.

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

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

A mutation tool with no annotations, no output schema, and two undocumented parameters gets one vague sentence. It does not tell the agent enough to call it safely or to predict the effect on agent/skill files.

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% for both required parameters. The description implies 'version' means the new version string but never defines its format, and 'project_root' is not mentioned at all, so the agent gets no help on scope or path expectations.

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 (update) and a resource (the auto block in agent & skill files), but 'auto block' is unexplained jargon and the description never ties it to the tool name 'procedure_block'. It is distinguishable from siblings like update_plan_section only by the words 'agent & skill files', which is thin.

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 guidance on when to call this versus ingest_procedure, list_procedures, or provision_agent_skill, and no preconditions stated. The agent must infer the workflow entirely from the name.

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 no annotations, the description carries the full burden and does disclose two important traits: private/loopback hosts are refused, and ingest:true writes the page into the knowledge base. It omits other behavior an agent needs – what happens on timeout, that output is truncated by max_chars, and how fetch failures are surfaced.

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 with no filler; the verb and return shape are front-loaded, and the constraint and the ingest flag follow in a sensible order. Minor loss only because the private-host rule could have been folded more tightly with the URL eligibility.

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 does name the return fields, which is the most important gap filled. Still, for a 5-parameter network tool with no annotations and 40% schema coverage, the missing max_chars/timeout semantics and failure behavior leave it short of fully sufficient.

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

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

Schema coverage is only 40%, so the description needs to compensate and does not: it explains url and ingest (both already documented in the schema) but says nothing about source, max_chars, or timeout_ms. The truncation default of 2000 chars in particular is invisible without reading the schema.

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

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

The description states a specific verb ('Fetch') plus resource ('public http/https URL') and the return payload ('title + readable text'). It is clear on its own, but it never distinguishes itself from the sibling browser_fetch or webfetch_validate, leaving an agent to guess which fetch tool applies.

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

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

It gives one real usage signal – 'Use `ingest: true` to also store the page in the knowledge base' – and an implicit eligibility rule (public only, private/loopback refused). It offers no indication of when to prefer this over browser_fetch or when to validate first with webfetch_validate.

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