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

With no annotations, the description carries the burden and does disclose that this is a cheap/local passthrough for mechanical tasks. However, it does not describe return format, error behavior, model fallback behavior, or authentication/permission expectations.

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 tightly written sentences, front-loaded with the tool’s role and followed by the two input modes. There is no redundant or padding 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?

The description covers the main invocation paths for a 14-parameter tool, but without an output schema it does not explain the return shape or limitations. Advanced parameters such as response_format, think, and max_tokens are left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters thoroughly. The description adds only high-level clarification that prompt/system are for one-shot use and messages supports few-shot or multi-turn conversations.

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 identifies a chat-completion passthrough to a cheap/local model and frames its role as offloading small mechanical tasks. It distinguishes the tool by cost and generality, though it does not explicitly name sibling alternatives.

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 clear usage modes: prompt plus optional system for one-shot completions, or messages for OpenAI-style conversations. It lacks explicit when-not guidance or named alternatives such as summarize, extract, or classify.

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 adds only that execution happens 'with the local model' (useful for local-vs-remote decisions), but says nothing about permission requirements, whether a model must be pulled first, cost/latency expectations, what the response contains, or how multi_label interacts with a single-label default.

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, so it is efficient and appropriately sized for the core assertion. It is arguably under-specified rather than concise, but as pure prose structure it wastes nothing.

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

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

A 15-parameter tool with a nested options object, no output schema, and no annotations needs more than one sentence to be safely invocable. The description omits the return shape, the local-model prerequisite, and any sibling routing, leaving significant gaps for an operation this complex.

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 73%, so most parameters (glob, path, text, multi_label, options, think) are already documented in the schema. The description adds nothing beyond echoing the label output, so the baseline of 3 is appropriate for a 15-parameter tool whose schema does the heavy lifting.

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

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

The description states a specific verb ('classify'), the resource ('text/file content'), and the output form ('one or more labels'), plus the execution venue ('with the local model'). It is clear on its own, but it never distinguishes itself from closely related siblings like extract, summarize, or decide, all of which also produce derived output from text.

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 statement, no condition for choosing between inline text, a single path, multiple paths, or a glob, and no mention of alternatives such as extract or decide. Usage is only implied by the required 'labels' parameter, leaving the agent to infer routing from siblings.

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 delivers: atomicity semantics, refusal-on-file-change with a force=true escape hatch, write_mode gating, and the user-facing approval-prompt consequences of argument choice. This is behavior an agent cannot infer from the schema.

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

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

Dense and front-loaded — the core action and precondition come first, then the refusal/force rule, then the mode gate, then batching. Every sentence earns its place, though the single long paragraph could break the batch guidance out more cleanly.

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 and no output schema, the description covers safety, preconditions, mode gating, failure behavior, and the batch path. An agent has everything needed to call it correctly without opening sibling schemas.

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

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

Schema coverage is already 80%, yet the description still adds value: it explains WHY path and summary are required (they are what the approval prompt displays) and why they must be precise, and it frames ops as the batch alternative to single-op fields. Minor gap: it doesn't clarify force versus the path/op_id pairing in edge cases.

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 ('Apply a staged write to disk') and immediately qualifies it with the mechanism ('atomic: tmp+rename'). This clearly separates it from sibling staging/proposal tools like propose_write and stage_delete.

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

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

Gives explicit preconditions ('Call only AFTER reviewing the diff with get_diff'), an explicit exclusion ('do NOT call it in propose mode'), and routes a specific sibling workflow ('use it for map_files stage_writes output'). When, when-not, and alternatives are all covered.

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

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

With no annotations, the description carries the full burden and largely meets it: pause is defined as halting 'between agent steps' (async checkpointing), cancel 'aborts in-flight work too' (stronger than pause), and inject's instruction is seen 'on its next step.' It still omits whether cancel is irreversible, whether resume works after cancel, and any permission/ownership requirements.

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 opens with the verb and resource, then lists the four actions with tight parenthetical clarifications. No sentence is filler.

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

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

For a 3-parameter control tool with no output schema and no annotations, the description gives an agent enough to choose an action and understand its effect. It leaves out job_id semantics and any statement about results/errors, which is a minor but real gap given the absence of an output schema.

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

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

Schema coverage is only 33% (just 'message'), but the description compensates well by defining the behavioral meaning of each enum value for 'action' beyond the bare enum list. The 'job_id' parameter is left entirely unexplained, and the inject/message dependency is only in the schema, so it does not fully close 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 ('Steer') plus resource ('a running background job') and enumerates every action it performs. This clearly separates it from read-oriented siblings like get_job, list_jobs, and wait_job without opening any schema.

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

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

Each action's intent is spelled out, and 'inject' is explicitly scoped to 'course-correcting a run_local_agent mid-flight,' which is genuine when-to-use guidance. It stops short of stating exclusions or naming alternatives (e.g., use get_job/wait_job instead when you only want status), so it is strong context without explicit 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 burden, and it delivers: it discloses the chars/4 heuristic, quantifies the error margin (±20% vs a real tokenizer), and scopes it as input sizing not billing. It stops short of explaining the return shape or whether paths are read server-side (left to the schema).

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

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

Two tight sentences, zero waste, with the core caveat (heuristic, ±20%) front-loaded and the usage guidance second. Every clause carries 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 simple utility with no output schema and no annotations, the description covers purpose, accuracy limits, and usage context well. The one gap is that, absent an output schema, it does not describe what is returned (per-file vs aggregate counts), which an agent might want.

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

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

Schema description coverage is 100%, so all four parameters (glob, path, text, paths) are already documented in the schema. The description's 'for text/files' only loosely gestures at the text-vs-file distinction without adding syntax or precedence rules, so 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 (estimate/count) and resource (tokens for text/files), and the parenthetical makes clear it is a sizing heuristic rather than a billing-grade tokenizer. This cleanly distinguishes it from the model/agent-running siblings like run_local_agent and summarize.

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?

Names the trigger scenario ('Use before run_local_agent/summarize to check fit vs num_ctx') and the purpose, which is strong routing guidance. It lacks an explicit when-not-to-use or a note about the other sizing siblings, so it falls just short of a full 5.

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

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

With no annotations present the description carries the full burden and does so: it discloses the single-forward-pass execution model, the deliberate absence of text generation/output parsing/retries, the 1–64 question cap, the server-side state read ('files never enter your context'), and the failure mode for non-decision models. This is behavioral context an agent could not get from the schema.

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

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

Front-loaded with purpose, then constraints, then the routing rule, then question types and requirements — each sentence carries distinct information. It is dense rather than padded, though the type-semantics block could be tightened slightly given the schema already constrains the enum.

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

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

For a tool with no output schema and a nested question object, the description still tells the agent what comes back (calibrated probabilities per option), what is required to run it, and how the nested question types behave. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 86%, so the baseline is 3; the description goes beyond it by explaining the 'choice' / 'score' / 'noul' question-type semantics, including that `criteria` maps option keys to descriptions and that a null value falls back to the key. It clarifies the server-side meaning of the state parameters, though it leaves `glob`/`paths`/`provider` largely to 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?

Starts with a specific verb+resource ('Decision-model scoring'), names the endpoint and the concrete models (clef / clef-flash / nimble / tev), and states the output ('calibrated probabilities per option'). It also explicitly distinguishes itself from the sibling `classify`, so an agent can pick 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 routing rule ('Prefer over `classify` when a decision model is available: you get real probabilities instead of parsed JSON') plus a hard precondition ('Requires an ollama provider running a decision model; a normal chat model returns an error'). Both when-to-use and when-it-fails are covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses irreversibility, the recovery path (the model must be re-pulled), and the exact guard conditions requiring force. It still leaves open what happens if provider is omitted and whether the operation is synchronous.

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 clauses with the endpoint first, then the irreversibility warning, then the guard conditions. Nothing is wasted and the most decision-relevant fact (irreversible) is 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 3-parameter destructive tool with no output schema, this covers the essentials an agent needs — reversibility, refusal conditions, and the force escape hatch. The missing piece is provider defaulting/resolution, which matters because provider is not required.

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 description adds real meaning for force (overrides the default/loaded-model protection) that the schema only hints at. However the provider parameter is undocumented in both schema and description, and the schema description coverage is only 67%, so the gap is not fully compensated.

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 plus resource (delete a model), scoped to an ollama provider and to the DELETE /api/delete endpoint. It is clear what the tool does, but it never distinguishes itself from siblings like unload_model, prune_models, or pull_model, which an agent could confuse with deletion or restoration.

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

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

It states meaningful preconditions — it refuses to delete the default_model or a currently-loaded model unless force=true — which effectively tells the agent when the call will fail. However, no alternative tool is named, so there is no guidance on when to delete versus unload or prune.

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 destruction of a staged op, but says nothing about reversibility, whether the op_id must be valid/staged first, what error occurs on an unknown id, or that nothing is written to the target resource. That is a significant gap for an irreversible 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 front-loaded sentence with no wasted words; the destructive intent leads. It is arguably too terse for a mutation tool, but there is no padding or redundancy.

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, one undocumented parameter, and irreversible semantics. The description should at minimum state the required precondition and what the caller gets back or loses; as written an agent cannot confidently invoke 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?

One required parameter exists and schema description coverage is 0%, so the description must compensate — but it never mentions op_id or where to obtain one (e.g., from list_staged or a prior propose_write). The parameter is left entirely to the bare schema type.

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 ('Drop') and resource ('staged write op') plus the key scope qualifier 'without applying it'. An agent can distinguish it from commit_write/propose_write, though it never names a sibling to sharpen the contrast.

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?

'Without applying it' implies this is the abandon path versus commit_write, giving implied usage context. But there is no explicit when-to-use statement, no mention of the alternative revert_write, and no stated prerequisite (e.g., the op must still be staged).

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 the most important trait: this is an asynchronous background job whose completion must be checked via get_job. It does not mention auth needs (HF token), disk-space/allowed-root constraints for local_dir, or failure behavior, which are relevant for a large download.

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 dense paragraph that front-loads the verb, source, and execution model, then supplies a concrete example. Every sentence carries information, though the parenthetical about serving stacks is slightly wordy.

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 download tool with no output schema, the description supplies the essential operational facts: source CLI, async execution, polling tool, and a concrete example. It omits what happens to the artifact on completion and any auth preconditions, which leaves a small gap but not a blocking one.

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

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

Schema description coverage is 100%, so all four parameters are already documented, and the description adds only a usage example pairing repo with include. That is a small increment over structured data, so the baseline 3 is appropriate.

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

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

States a specific verb (download) and resource (a model from Hugging Face) and explicitly differentiates itself from the sibling pull_model ('where pull_model doesn't apply'). An agent can route between the two download paths 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?

Names the alternative tool (pull_model) and the class of servers where this tool is the right choice, plus the follow-up action (poll with get_job). The selection condition is a bit loose ('llama.cpp/TabbyAPI/vLLM-style servers'), so it stops short of an explicit decision rule but still gives clear 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?

With no annotations, the description carries the full burden and does useful work: it declares the prerequisite (an embedding model, with concrete examples), and discloses the return shape ('raw vectors; cosine-similarity them yourself'). It doesn't mention permissions, rate limits, or batch semantics, keeping it below 5.

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

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

Three tightly written sentences: the purpose leads, the prerequisite follows, and the output caveat closes. Every sentence carries information an agent needs, 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?

With no output schema or annotations, the description supplies the key missing context: model requirement, discovery route via list_models, and the raw-vector return format. Remaining gaps around parameter interplay and input precedence are minor for a 6-param tool with no required fields.

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%, so most parameters are already documented in the schema, and the description adds little beyond implying the text/file/model/provider inputs. Naming example models ('nomic-embed-text', 'embeddinggemma') adds minor semantic value for the model parameter, but no guidance on how glob/path/paths interact.

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 ('Embed text/files with an embedding model') and scopes the intent to semantic dedup, clustering, and find-similar work. It distinguishes itself from generation-based siblings and names list_models as the discovery path, so an agent can route without opening the schema.

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

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

Provides clear context: use for embedding tasks that 'generation can't do', and instructs the agent to check list_models for embedding-capable models. It lacks an explicit when-not or a named alternative tool for the same task, so it falls short of a 5.

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

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 two genuinely useful traits: local-model execution and one automatic retry on invalid schema output. It omits operational realities for a 15-param inference tool — whether the model must be pulled first (siblings include pull_model/list_models), latency or timeout behavior, and what happens on retry failure.

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

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

Two sentences, zero filler, with the core action front-loaded and the optional validation behavior trailing it. Every clause carries 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 15-parameter tool with no output schema, the description should say what comes back — raw JSON object, string, or wrapper with metadata — and how the file-input variants relate. Neither the return shape nor the input-mode selection is covered, leaving substantial gaps for an agent assembling a call.

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

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

Schema coverage is 73%, so the schema documents most parameters and the baseline is 3. The description adds only that extraction works over 'text/files' and that 'schema' triggers validation with a retry, but says nothing about the mutual exclusivity of text/path/paths/glob or the model/provider/options relationships it exposes.

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 (extract structured data from text/files) and the execution locus (local model), which implicitly separates it from sibling inference tools like classify, chat, and summarize. It stops short of naming any alternative explicitly, so it lands at 4 rather than 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 never says when to reach for this instead of the other model-backed siblings (classify, summarize, decide, chat, run_local_agent). The schema-validation mention hints at a context, but there are no stated conditions, prerequisites, or exclusions.

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 disclose meaningful behavior: it is an inspection operation ('Show'), and execution semantics are argv-level with no shell. It does not state permissions, side effects, or response format, but for a simple getter the key behavioral trait is covered.

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

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

A single front-loaded sentence with no wasted wording. The resource and critical scoping constraint ('argv-level whitelist, no shell') appear immediately.

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 read-only getter with no output schema, the description gives enough context to select and invoke the tool correctly. It does not describe the exact return structure, but the core semantics are complete enough for this simple operation.

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?

This tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description appropriately does not invent any.

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 specific verb 'Show' with the precise resource 'which commands the local agent's run_command tool may execute,' and it adds the key scope 'argv-level whitelist, no shell.' This clearly distinguishes it from the sibling update_command_whitelist, which would mutate rather than inspect the whitelist.

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: an agent would use this to inspect the effective command whitelist for run_command. However, the description does not explicitly say when to prefer this over siblings such as update_command_whitelist or run_local_agent, nor does it mention prerequisites or exclusions.

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 behavioral burden. 'Show' implies a read-only operation, but it says nothing about behavior when op_id is invalid, whether output is paginated, or whether viewing has any side effects, leaving a mutation/read gap unresolved.

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, which is efficient and easy to parse. It borders on under-specification rather than true concision, but structurally it is clean.

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, the description needs to do more work: it does not describe the diff's return format, the meaning of op_id, or what include_content yields beyond the schema's own hint. For a 2-parameter tool with a 50% documentation gap, this is incomplete.

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%: include_content is documented in the schema, but the required op_id has no description anywhere. The phrase 'for a staged write op' only faintly hints that op_id identifies that op, so the description fails to compensate for the documentation gap on the mandatory parameter.

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 ('Show the unified diff') scoped to 'a staged write op', so the agent knows exactly what it returns. It does not, however, differentiate itself from siblings like verify_staged or list_staged, which an agent could confuse with this read.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite closely related siblings (verify_staged, list_staged, get_job). The 'for a staged write op' phrase only weakly implies the context; the agent must infer selection criteria on its own.

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 disclose what the call returns (status and progress of a background job), which is useful since there is no output schema, but it says nothing about permissions, behavior for an unknown/invalid job_id, or whether polling is expected.

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 tight sentence with the purpose front-loaded and no wasted clauses. The parenthetical example adds real context rather than padding, though the sentence is close to the minimum viable length.

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

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

For a simple single-parameter read tool with no output schema, the description conveys the return content but omits how to obtain a job_id and how this differs from wait_job/list_jobs. With no annotations and no output schema to fall back on, it is adequate but leaves clear gaps.

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

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

Schema description coverage is 0% and the description never mentions the single parameter. It does not explain what a job_id is, where the agent obtains one (e.g. from list_jobs or pull_model), or its expected format, so the parameter is effectively undocumented in both structured and natural-language fields.

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+resource pair ('Get status/progress of a background job') and clarifies scope with an example ('e.g. a model pull'), so an agent knows it reads job state rather than managing jobs. It does not, however, explicitly distinguish itself from close siblings like list_jobs, wait_job, or control_job.

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 wait_job (which presumably blocks until completion) or list_jobs (which presumably enumerates jobs). The 'e.g. a model pull' example hints at context but does not tell the agent how to choose among the job-related siblings.

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 the behavioral load, and it does disclose that providers are 'sanitized' (secrets redacted) and that the response is a scoped config view. It does not explicitly state read-only/no-side-effects or any permission requirement, so a small gap remains, but the sanitization note is a meaningful 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?

Two short sentences, zero waste: the contents list is front-loaded and the 'call this first' guidance follows. Every clause 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?

With no output schema, the description compensates by enumerating the returned fields (providers, allowed_roots, feature flags, limits), so an agent knows what to expect. Combined with the orientation hint, nothing needed to invoke this zero-arg tool 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?

The tool takes zero parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate beyond the empty input 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 ('Show') and resource ('this server's config') and enumerates exactly what is returned: providers, allowed_roots, feature flags, limits. An agent can distinguish it immediately from config-mutating or model-related siblings like set_write_mode or get_command_whitelist.

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 says 'Call this first if unsure what's configured', which gives a clear triggering condition. It stops short of naming alternatives or when NOT to call it, but the orientation advice is 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 burden and does well: it discloses the failure-mode return value ({unavailable: true} for remote/openai providers) and the meaning of the ollama_gpu field including how it is derived (env pinning vs runner process device fds). It doesn't discuss cost/latency, but for an informational read tool this is solid 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 front-loaded sentences with no filler; purpose, constraint, and usage all arrive early. The final sentence on ollama_gpu is slightly technical but its detail is load-bearing for interpreting the result.

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, the description covers the key return values ({unavailable: true}, ollama_gpu) and the provider-scoped behavior, which is most of what an agent needs. Minor gaps remain around the provider parameter's accepted values and whether other fields are 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 provider parameter has 0% schema description coverage, so the description must compensate. It adds useful domain context by distinguishing local ollama vs remote/openai provider behavior, but never enumerates accepted provider values or states whether the param is required/defaulted.

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: reports host RAM, GPU VRAM, and currently-loaded models. The scope is distinct from model-listing siblings like list_models or get_server_info, though no sibling is named to explicitly route the agent away from them.

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

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

Gives explicit when-to-use ('Use before picking a model or num_ctx for heavy jobs') and an explicit when-not ('Only works for LOCAL ollama providers — returns {unavailable: true} for remote/openai-type providers'). The agent knows both the trigger and the failure condition.

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 the meaning of delegated_bytes (server-side processed content that never entered context, i.e. the savings), which is genuinely useful context. However it is silent on read-only guarantees, session scope boundaries, or reset 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?

A single dense sentence that front-loads 'Session totals' and enumerates its three metrics with a clarifying parenthetical for the only non-obvious one. No filler.

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

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

With no output schema, the description must carry the return-value burden, and it defines the three headline metrics including delegated_bytes. It is nearly complete for a zero-parameter read tool, though it does not state the session/time window precisely or the exact shape of the returned 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?

The tool takes zero parameters, so the baseline of 4 applies. The schema has no parameters to document and the description appropriately focuses on what the metrics mean rather than inventing input semantics.

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

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

The description names the resource (session totals) and enumerates the specific metrics returned: local LLM calls, tokens on the cheap model, and delegated_bytes. It is clearly a read-only stats retrieval tool, distinguishable from siblings like count_tokens or get_system_resources, though it does not explicitly contrast itself with 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?

There is no statement of when to call this tool, when not to, or which sibling to prefer for related questions (e.g. count_tokens, get_system_resources, get_job). The agent must infer usage purely from the metric names.

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 for a tool with zero parameters. It doesn't say whether this is a safe read, whether the list is paginated, whether it reflects session-local vs global registrations, or what happens when nothing is registered.

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 verb and scope lead and nothing 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 zero-param, read-only discovery call with no output schema, the description conveys enough to invoke it correctly. It is only slightly thin on the semantics of what 'runtime-registered' and 'local agent' encompass.

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; schema coverage is 100% by vacuity. Baseline 4 for a zero-param 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?

States a specific verb (list) and resource (runtime-registered agent tools) with clear scope ('available to the local agent'). It reads distinctly from sibling list_models/list_jobs, though it never explicitly contrasts itself with register_agent_tool/unregister_agent_tool, which cover the adjacent lifecycle.

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 reference to any alternative. The agent gets no signal about when discovering runtime tools is preferable to, say, reading a static list or calling register_agent_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?

No annotations are provided, so the description bears the behavioral disclosure burden. It usefully discloses a bounded result ("last 20"), but does not explicitly state read-only behavior, side effects, permissions, or return shape.

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 waste. The result bound and intended use are stated immediately.

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 list tool with no output schema, the description gives enough to know the scope and intended use, but not enough to know what the returned items look like. Since no output schema exists, the omitted return-value detail is a meaningful 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?

The tool has zero parameters, so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, this is adequately covered by the schema and does not require additional description detail.

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 recently committed writes, capped at the last 20. It also ties the tool to revert_write, which helps distinguish it from commit/staged-write siblings, though it does not explicitly name list_staged as the alternative.

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 revert_write" gives a clear intended use case, but there is no guidance on when not to use it or what sibling to use instead. The usage is implied rather than fully 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?

No annotations are provided, so the description carries the full burden and largely does not. It does disclose result ordering ('most recent first'), which is genuine added value, but says nothing about pagination, result limits, or what fields a job record includes.

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 '(most recent first)' parenthetical earns its place by conveying ordering.

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

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

With no output schema, the description should at least hint at what a listed job contains or whether results are bounded, and it does neither. For a zero-parameter read tool the gap is minor but real.

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 baseline of 4 applies; there is no parameter syntax for the description to clarify.

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 ('List') and resource ('background jobs'), which inherently separates it from the singular get_job and the action-oriented wait_job/control_job siblings. It does not explicitly name an alternative, 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 when-to-use guidance, no prerequisites, and no routing to get_job or wait_job. The intent to enumerate jobs is only inferred from the verb 'List'.

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 and no output schema, the description carries the full disclosure burden; it does usefully note that ollama providers return size, parameter count, quantization and capabilities. It says nothing about auth, pagination, or failure behavior for remote providers, leaving meaningful gaps.

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

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

Two sentences, zero filler, with the core action front-loaded and the workflow hint following immediately. Every clause 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 single-parameter read-only listing tool with full schema coverage, the description covers purpose, provider scope, and an intended follow-up workflow. The main omission is broader return-shape description for non-ollama providers, which matters somewhat given there is no output schema.

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

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

Schema coverage is 100% and the single 'provider' parameter is fully documented in the schema, including the default and 'all' semantics. The description only restates the provider scoping concept, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (list models) scoped to a provider, which is concrete and actionable. It doesn't explicitly distinguish itself from similarly-named siblings like list_model_tags, search_models, or recommend_model, so an agent must infer the difference from the description's VRAM-selection framing.

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 clear intended use: pair with get_system_resources to pick the biggest model that fits VRAM, naming a companion tool explicitly. It lacks any when-not guidance (e.g., vs. search_models or list_model_tags), so the routing is only partially resolved.

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 well: it discloses the external dependency ('Requires internet access') and a real cost trait ('one request per tag' when include_sizes=true), which is the kind of per-call performance behavior an agent needs. It stops short of covering failure modes (rate limits, timeouts, model-not-found) or whether results are cached, so it is strong but not exhaustive.

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

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

Three compact sentences, front-loaded with the core purpose, then the optional-cost behavior, then the hard prerequisite. No filler and nothing restated from the schema verbatim.

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

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

For a 4-parameter, no-output-schema tool the description covers purpose, cost, and prerequisite well. The remaining gap is return shape: whether the result is a plain list of tag strings and how sizes are keyed when include_sizes=true is left to inference.

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 baseline is 3. The description reinforces the include_sizes cost model ('one request per tag') beyond the schema's 'slower' note and clarifies the model format via example, but adds nothing for the 'provider' parameter and no defaults or return ordering.

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

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

States a specific verb and resource ('List pullable tags for a model in the ollama registry') and grounds it with a concrete example ('gemma4' -> e4b, 12b, 26b). An agent can distinguish this from siblings like list_models and search_models without opening the schema.

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

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

The description implies the scenario (you want the pullable variants of a model before pulling) and gives a clear tradeoff rule for include_sizes ('slower', 'one request per tag'), but never states when to prefer this over search_models or list_models. Usage is inferable rather than explicit.

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. It does add real behavioral signal by stating the writes are 'pending' and 'not yet on disk' (i.e. inspective, no side effects), but it never states read-only status, auth requirements, pagination, or result shape, and there is no output schema to fall back on.

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 resource first and the clarifying state qualifier immediately after. Every clause earns its place and there is 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?

For a zero-parameter, side-effect-free listing tool with no output schema, the description supplies enough to call it correctly: what is listed and what state those items are in. Only the return shape and read-only guarantee are left unstated, which is minor at this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level guidance is needed or 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 description gives a specific verb (list) and resource (pending staged writes), with the parenthetical 'proposed changes not yet on disk' pinning down the exact state being enumerated. That scope distinguishes it implicitly from commit_write, list_commits, and verify_staged, 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?

Usage is only implied: an agent can infer this is the inspection step before commit_write/discard_write. There is no explicit when-to-use statement and no named alternative (e.g. get_diff or verify_staged) to route against, so the guidance is minimal but not absent.

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 well on the critical dimension: it explicitly states that stage_writes produces a staged diff and 'NOTHING hits disk until you commit_write', which is exactly the kind of safety/mutation context an agent needs. It is silent on other traits: batch size limits, ordering, failure handling per file, and the cost/latency of running a local model over many files.

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 with zero filler: the batch operation is front-loaded, then the two output modes are enumerated with the safety note attached to the riskier one. No restatement of the tool name or schema content for its own sake.

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 14-parameter tool with no annotations and no output schema, the description covers the decisive choices (mode selection and the staging guarantee) but skips return shape for report mode beyond 'per-file results', default concurrency/model behavior, and any limits. Adequate to call it, not sufficient to predict its behavior or output.

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 57%, so some parameters (glob, seed, stop, think, options, concurrency, instruction) are already documented in the schema. The description adds genuine meaning for the undocumented 'output' enum pair and reinforces the instruction contract for stage_writes. But high-impact parameters such as model, provider, num_ctx, max_files, and temperature remain unexplained in both places.

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

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

The description states a concrete verb+resource: 'Run one instruction over many files with the local model (batch job)', and clarifies scope with the parenthetical 'batch job'. It distinguishes the two output modes, but does not contrast itself with adjacent siblings such as propose_edit, run_local_agent, or extract, which an agent may weigh for similar work.

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 real selection guidance between the two output values (report vs stage_writes) and names the downstream commit_write step, which is the key routing decision. However, it never says when to prefer map_files over sibling tools like propose_write/propose_edit or run_local_agent, so the broader when-to-use question 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 burden. It usefully discloses that the server applies the hunks and stages the result through the same diff/commit flow, so the agent knows this does not write directly. It does not cover failure modes (e.g. hunks that fail to apply), permissions, or whether an existing staged op is affected.

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 differentiation from propose_write and the reliability rationale are 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 mutation tool with no annotations and no output schema, the description covers the core flow (hunks applied server-side, result staged like a normal op) adequately. Gaps remain around error handling and the many LLM sampling parameters, but the critical staging semantics are 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 description coverage is 70%, so the schema documents most of the 10 parameters (path, seed, stop, think, options, instruction). The description adds no parameter-level detail beyond implying the instruction drives hunk generation, leaving the sampling params entirely to the schema.

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

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

States a specific verb and mechanism (local model emits SEARCH/REPLACE hunks) and explicitly positions itself against the sibling propose_write. An agent can distinguish it from propose_write 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 clear selection context — prefer this for large files and small models where whole-file emission is unreliable — and frames itself as a variant of propose_write. It stops short of an explicit exclusion list (the 'use propose_write for new files' rule lives in the schema, not the description).

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 burden, and it does well: it discloses that output is staged, returns an op id + diff, and that nothing is written until commit_write. It doesn't cover failure modes (e.g., rewriting a nonexistent path) or auth/model availability requirements, keeping it short of a 5.

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

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

Three sentences, front-loaded with the core action, then the return/staging contract, then the usage condition. No wasted 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 10-param mutation tool with no output schema, the description covers the workflow contract (staged, op id + diff, commit gate) well. It is slightly thin on the many provider/sampling parameters, but a caller can rely on the schema for those.

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 70%; the description adds no parameter-level detail beyond what the schema already provides. It never explains sampler params, think, options, or provider behavior, so it neither compensates for the uncovered params nor adds meaning over the schema. Baseline 3 is appropriate.

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

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

States a specific action (rewrite/create ONE file), names the local model as the actor, and frames the tool as a staging step. It clearly distinguishes itself from sibling commit_write by stating 'Nothing is written until commit_write' and from propose_edit/propose_write family by scoping to one file.

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 condition: 'Use for mechanical rewrites where the file content shouldn't flow through your own context.' This tells the agent when this tool is preferable, though it doesn't name the alternative sibling (e.g., propose_edit) or state a when-not case.

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, and it does substantial work: it discloses the destructive scope ("deletes the rest"), the safety guardrail set (keep[], default_model, loaded models, keep_recent), and the dry-run default. It omits recovery/permission implications and what the dry_run report 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?

Three sentences, front-loaded with the purpose, then the safe default, then the retention rule. No filler and every sentence carries operational 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 destructive bulk tool with no annotations and no output schema, the description covers purpose, safety default, and retention adequately. The remaining gap is that two of the six parameters (the age/usage retention filters) and the shape of the dry-run report are not described, which slightly underspecifies pruning 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 coverage is moderate (67%), and the description adds real value for dry_run by explaining its default-on reporting semantics beyond the bare schema default. However it never mentions the unused_days or max_age_days retention parameters, so its stated "always keeps" list is incomplete relative to the actual retention logic.

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 ("Bulk-delete old models") plus a scope qualifier ("from an ollama provider"), which is clearly distinct from the single-model siblings delete_model and unload_model. An agent can identify the operation without opening the schema.

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

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

Explains the dry_run=true default workflow ("only reports candidates") and the conditions under which deletion actually occurs with dry_run=false. It does not explicitly name delete_model/unload_model as alternatives or state when not to use the bulk path, so it stops short of full when/when-not 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, the description carries the full burden and does well: it discloses that the call runs as a background job, returns a job_id, and that progress is polled via get_job. It omits expected duration, failure modes, and whether re-pulling an existing model overwrites it.

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

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

Three short sentences, front-loaded with what the tool does and immediately followed by the async behavior and follow-up tool. No wasted 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?

Covers purpose, the ollama constraint, the async return (job_id), and the polling path, which is the key information for a two-parameter tool with no output schema. Minor gaps around the undocumented provider parameter and failure handling remain.

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%: model is documented in the schema, while provider is not. The description compensates by giving the model-name format example ('qwen2.5-coder:7b') and implying provider meaning through the ollama restriction, so it edges above baseline but doesn't fully explain the provider parameter's accepted values.

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 ('Download a model') and scopes it to ollama providers, which separates it from generic siblings. It does not, however, distinguish itself from the sibling tool download_model, which an agent could easily confuse it with.

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?

'Only for ollama providers' gives one usage condition, but there is no explicit when-to-use versus download_model, the obvious alternative, nor any notes on prerequisites. Usage is implied rather than fully guided.

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 well: it discloses the selection heuristic (prefers tool-calling models fitting free VRAM, or free RAM for CPU-only) and the write side effect of apply=true ('writes the pick... AND applies it live'). It stops short of stating failure behavior when nothing fits or permission requirements.

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 tightly packed sentences: the core recommendation purpose leads, the selection heuristic follows, and the mutating apply behavior closes. Every clause carries information and nothing is redundant.

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

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

For a tool with full schema coverage and no output schema, the description supplies the missing behavioral context (selection criteria and the apply side effect). It's nearly complete; only failure/edge-case behavior when no model fits the budget is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, which sets a baseline of 3. The description adds some behavioral meaning for apply (config write + live application), but adds nothing beyond the schema for model, provider, or budget_mb.

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 ('recommend a default_model') and resource (a provider's default model) and pins down the unique logic: analyzing installed models against detected hardware. This clearly separates it from siblings like list_models or get_system_resources, which only surface raw data rather than producing a recommendation.

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 implies usage through the apply=true clause (persist/live-apply) but never states when to prefer this tool over list_models or get_system_resources, nor any prerequisites or exclusions. The intended workflow is inferable but not spelled out.

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: persistence semantics (session-only unless persist=true), execution model for both kinds (execFile with no shell; node:vm (body)(args)), and the required server env var. The 'no shell' detail is important security-relevant disclosure beyond structured data.

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

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

Front-loaded with the core purpose, then the persistence nuance and per-kind semantics. Dense but every clause is content-bearing; no filler. Slightly packed into one paragraph rather than crisply separated.

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

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

For a complex 8-param registration tool with a nested input_schema and no output schema, the description covers persistence, both execution kinds, and the env prerequisite. It stops short of naming collision/error behavior or confirming the return, which would fully close the loop.

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 high (88%), so baseline is 3, but the description adds real meaning by explaining how kind='shell' consumes command/args_template with ${param} placeholders and how kind='js' consumes body. This ties the enum branches to their parameters in a way the terse schema descriptions do 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?

Starts with a specific verb+resource ('Register a NEW tool') and immediately scopes it as something the local model can call during run_local_agent. The word 'NEW' implicitly distinguishes registration from the sibling list_agent_tools/unregister_agent_tool operations, and it names run_local_agent 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?

Gives clear context (dynamic tools callable during run_local_agent) plus a hard prerequisite (LOCAL_LLM_DYNAMIC_TOOLS=1) and the session-vs-persistent behavior. It does not explicitly contrast with unregister_agent_tool/list_agent_tools, so when-not guidance is absent, but the usage conditions are clear.

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

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

With no annotations, the description carries the full burden and delivers the single most important non-obvious fact: this is not an immediate undo, it stages a new op that must pass review and be applied by commit_write. It does not cover permissions, whether the revert can itself be undone, or 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?

A single front-loaded sentence that states the action first and the mechanism second, with no filler. Every clause 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 one-parameter mutation tool with no annotations and no output schema, the description covers the essential semantic surprise (staged, not immediate) and the follow-up call needed. Missing only the return value (e.g., the new staged op id) and error conditions.

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 required parameter (commit_id) at 0% schema coverage, so the description must compensate. 'Pre-commit content' and 'a committed write' strongly imply commit_id identifies the commit to revert, but the description never defines the parameter or its expected format.

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 ('Undo a committed write') and immediately clarifies the mechanism: it stages a NEW op rather than reverting in place. It names commit_write as the applier, which differentiates it from that sibling, but does not distinguish it from uncommit_write or discard_write.

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 'goes through normal review — commit_write applies it' implies the workflow (revert, then commit) but never states when to choose this over uncommit_write, discard_write, or stage_delete. Usage is inferable from context rather than explicit.

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 does substantial work: it discloses that execution is entirely server-side, that file contents and intermediate steps never enter the caller's context, and that the return is a compact answer plus staged-write op ids to review. It leaves out some operational details (cost/latency expectations, failure modes, whether staged writes must be committed via commit_write), which keeps it short of a 5.

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

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

Two tight sentences front-load the core mechanism and the return contract before the usage rule, with zero filler. Slightly dense but every clause carries information relevant to correct invocation.

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 15-parameter tool with no output schema, the description adequately covers what the agent must know: execution isolation, the shape of the result, and the delegation boundary. It omits the tuning parameters and the staged-write review/commit workflow, which are handled by sibling tools, but the core mental model is complete.

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

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

Schema coverage is 67%, so the schema already documents most parameters including the important task, files, paths, and run_async semantics. The description adds a useful distinction between inlining files versus pointing at paths, but says nothing about model, provider, max_steps, timeout_s, temperature, options, or num_ctx, so it only marginally extends 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+resource: delegating a low-complexity task to a local subagent that runs its own server-side tool loop, and names the exact tools it can call (read_file, list_dir, search_files, stage_write, run_command). It is clearly distinguishable from siblings like chat, summarize, and map_files because it describes an autonomous agent loop rather than a single-shot call.

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 names when to use it (mechanical, monotonous, or bulk work: finding things, transforming files, answering questions over many files) and when not to (work needing real reasoning, security judgment, or architecture decisions). This is a complete routing rule an agent can apply without 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 burden and does reasonably well: it discloses the return payload (name, description, capability chips, parameter sizes, install status) and a network dependency. It omits failure/offline behavior and rate-limit or pagination 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?

Three tight sentences: purpose and workflow first, return shape second, precondition last. No filler and nothing redundant with structured fields.

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 read-only search tool with no output schema, the description covers purpose, the downstream consumer, the shape of returned data, and the network requirement. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the category enum and limit bounds. The description only loosely echoes them ('capability chips', 'already installed'), adding no syntax or format detail beyond the schema; 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 (search) and resource (public ollama registry at ollama.com), and explicitly frames the result as input to pull_model. The 'public registry' scoping cleanly separates it from local-model siblings like list_models.

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 models to pull_model' establishes the intended workflow and the 'requires internet access' note flags a precondition. It stops short of an explicit when-not or naming the local alternative (list_models) for already-installed families.

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 present, the description carries the behavioral burden and does disclose substantive traits: the default posture, the cross-tool effect that commit_write is refused in 'propose', and that persist=true writes the choice into the server config file. It does not cover whether the setting survives restarts beyond the persist flag, nor any permission requirements, leaving some gaps for a state-changing server-wide switch.

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 tool's action, then the mode semantics, then the persist flag. No filler or repetition of the 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?

No output schema exists, so the description needn't explain returns, and it covers both parameters and the cross-tool effect of the mode switch. Only minor gaps remain (persistence across restarts beyond persist, and whether the change is reversible) for a global server-state mutation.

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 'mode' enum carries no per-value description in the schema, so the description does the heavy lifting: it names the default ('propose'), defines what staged writes mean in each mode, and clarifies persist=true as 'also writes the choice to the server config file'. This adds meaning well beyond the bare enum and the existing persist 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 and resource ('switch the server's write posture') and immediately distinguishes itself from the write-path siblings (commit_write, propose_write) by explaining what each posture does. An agent can tell what this tool is for without opening the schema.

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

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

The description explains the consequence of each mode (in 'propose', commit_write is refused and the agent applies diffs with its own tools; in 'write', commit_write writes staged ops to disk), which effectively tells the agent which mode to select for which workflow. It stops short of an explicit 'call this before X' instruction or any exclusion, so it is clear context rather than full when/when-not 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, so the description carries the full burden, and it does substantial work: 'nothing touches disk until commit_write', the diff shows all lines removed, and uncommit_write restores the file. It still omits failure behavior (e.g. nonexistent path, rejected review) and permission/auth considerations, which is the only real gap for an unannotated mutation-style tool.

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

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

Three compact clauses that front-load the action and the safety guarantee, then the diff effect, then the alternative. No filler sentences.

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, the description covers the full lifecycle an agent needs: staging, commit, and undo. Return/diff format and error handling are the remaining unstated items, but nothing critical to calling it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no meaning beyond the schema for 'path' or 'reason'; the only parameter-adjacent constraint ('inside allowed roots') is already stated in the schema itself.

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 ('Stage a file DELETION') plus the scope of the action. It explicitly contrasts itself with the sibling propose_write, so an agent can distinguish it without opening any schema.

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

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

Explicit when-to-use ('for dead-code cleanup instead of emptying a file with propose_write') and names the follow-up/undo path (commit_write, uncommit_write). The alternative and the condition that selects it are both spelled out.

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 discloses the key trait: files are read server-side and never enter the agent's context, with only summaries returned. That materially affects tool selection. It omits other relevant behavior such as latency of local-model calls, error handling, or determinism despite a seed parameter.

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 core purpose, followed by the context-safety behavior and the usage recommendation. No filler; 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 16-parameter tool with no output schema and no annotations, the description is thin: it never clarifies the four mutually exclusive input modes (glob/path/paths/text), which is essential for correct invocation. It does cover purpose and the primary behavioral benefit, so it is adequate but not complete.

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

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

Schema coverage is 75%, so most parameters are documented in the schema itself. The description only implies input modes ('files or text') without explaining glob vs path vs paths vs text, and adds no meaning for seed, think, concurrency, or model. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

States a specific verb+resource: 'Summarize files or text with the local model.' An agent immediately knows this produces summaries of files or text. However, it does not differentiate itself from nearby siblings like extract, classify, or chat, which could also be applied to text.

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

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

Gives a clear usage recommendation with a rationale: 'Prefer this over reading large files yourself.' This tells the agent when this tool wins (large files, avoiding context bloat). It stops short of naming alternatives (e.g. extract, chat) or stating when NOT to use 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?

With no annotations provided, the description carries the full burden and does so well: it discloses atomic restoration, deletion of files created by the commit, no re-staging/re-commit need, refusal on file drift, and the force override. These are the critical behavioral traits an agent needs before invoking a destructive undo.

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

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

The definition is compact and front-loaded: the core undo behavior appears first, followed by the refusal condition and mode requirement. Every sentence adds operational guidance 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?

For a two-parameter mutation tool with no annotations and no output schema, the description covers the critical invocation conditions: atomic restore behavior, mode gating, drift refusal, and the alternative path in propose mode. Return values need not be explained because no output schema exists.

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%: force is documented in the schema and reinforced by the description, but commit_id has no schema description and the description does not explicitly explain its role. The description adds useful context around force and the workflow, but does not fully compensate for the undocumented required parameter.

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: undo a committed write and restore pre-commit content atomically. It distinguishes this from related write-path tools by explaining the no-recommit behavior and naming siblings used in propose mode.

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 explicit when-to-use and when-not-to-use guidance: requires write_mode 'write', and in 'propose' mode directs the agent to revert_write + commit_write instead. It also states the file-drift condition and the force override.

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. It states that memory is freed immediately, but does not explain whether the model remains on disk, what permissions are needed, whether the operation is reversible, or what the return behavior is.

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 filler. It communicates the core action and immediate effect efficiently.

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 0% schema description coverage, the description is too sparse. It identifies the action but omits parameter guidance, usage context, side effects, and safety information needed for reliable invocation.

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

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

Schema description coverage is 0% and neither parameter has a description in the schema. The description mentions 'model' and 'ollama provider', which loosely maps to the two parameters, but it does not clarify requiredness, provider values, defaults, or what happens if provider is omitted.

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 a specific verb ('unload') and resource ('model'), and scopes it to VRAM on an ollama provider, which distinguishes it from disk-deletion siblings like delete_model. However, it does not explicitly name or contrast with any sibling tool, so it falls short of perfect differentiation.

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 implies the tool is used to free VRAM, but gives no explicit when-to-use guidance, no prerequisites, and no alternatives such as delete_model or prune_models. An agent must infer the selection context 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. It says nothing about whether the operation is idempotent, what happens if the named tool does not exist, whether removal affects in-flight jobs, or whether it requires elevated permissions — significant gaps for a destructive 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 front-loaded sentence with zero waste, which is appropriate for a simple tool, but the brevity comes at the cost of under-specification rather than genuine economy.

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

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

With no annotations, no output schema, and an undocumented required parameter, an agent cannot tell what constitutes success or how errors surface. For a mutation tool, more behavioral detail is needed than this one-liner provides.

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 'name' has 0% schema description coverage, and the description never mentions it or explains that it must match the registered tool's identifier. An agent must guess whether 'name' is a human-readable label, a full qualified identifier, or something else.

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 ('Remove') and a well-defined resource ('runtime-registered dynamic tool'), which cleanly separates it from the sibling register_agent_tool and list_agent_tools. It doesn't explicitly name those siblings, but the resource phrasing is distinctive enough to disambiguate.

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 use this versus register_agent_tool/list_agent_tools, and no stated preconditions (e.g., the tool must already be registered). Usage is only inferable from the name and the word 'runtime-registered'.

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 side effect ('Writes the server config file') and a security caveat, but omits whether add merges or replaces existing entries, whether remove is idempotent, whether failures roll back the config, and what permissions the write actually requires.

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, each earning its place: purpose first, then the write side effect plus a preference, then the permission recommendation. No padding or redundancy.

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 config-mutating tool with no annotations and no output schema, the description covers what it does and flags the write, but leaves merge/replace behavior, error handling, and interaction with the read counterpart unexplained. 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?

Schema description coverage is reported at 0%, so the description needs to compensate for two undocumented top-level parameters. It only gestures at allow_args ('prefer tight allow_args') and gives no meaning for add vs remove structure, the command name/basename format, or the null = any args semantics.

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

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

States a specific verb pair (add/remove) and the exact resource (commands the local agent may run), which lets an agent distinguish it from the read-only sibling get_command_whitelist. It stops short of explicitly naming that sibling, so the differentiation is inferred rather than stated.

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?

Offers real guidance on posture ('prefer tight allow_args over broad access') and on permission placement ('should stay in Devin's ask permissions'), which is context an agent would not otherwise have. However, it never states when to call this versus get_command_whitelist or what preconditions (existing whitelist, agent registration) are needed.

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 richly: temp-file materialization in the same directory, argv placeholder substitution and append-if-absent rule, whitelist enforcement, restore_paths snapshot/restore semantics, and guaranteed temp-file cleanup. It leaves little behavioral ambiguity about side effects on the target file.

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 but front-loaded, leading with the core action and scope before mechanics. Every sentence carries information, though the middle clause about import/path resolution is somewhat run-on 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 complex 5-param mutation-adjacent tool with no annotations and no output schema, the description covers inputs and side effects thoroughly. The one remaining gap is what the command returns (exit status, stdout/stderr), which an agent would need to interpret the result.

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

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

Schema coverage is 80%, so the schema already documents cwd, argv, timeout_s, and restore_paths. The description still adds real meaning: how '{file}' is substituted/appended in argv and how restore_paths are snapshotted and restored. The only gap is op_id, which neither schema nor description clarifies.

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 ('Run a whitelisted command against a staged write') with a precise scope constraint ('WITHOUT touching the target file') that separates it from commit_write and propose_write. An agent can distinguish it from siblings without opening any schema.

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

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

Explicitly prescribes when to use it ('typecheck/lint a staged op before commit_write') and warns why the naive alternative fails ('running a checker on the original path sees the OLD on-disk content'). It names the alternative tool and the condition selecting this one.

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 well: it discloses the 600s cap, the blocking-then-return semantics, and the early-exit trigger states (done/error). It doesn't state that this is a harmless non-mutating operation, but for a pure wait primitive the behavioral disclosure is nearly complete.

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

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

Two sentences, no filler, front-loads the primary action before the conditional job_id behavior and the routing hint.

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 2-parameter, no-output-schema wait tool, the description covers duration, cap, early-return semantics, and the motivating use case — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented (seconds with max/min, job_id as early-return trigger). The description adds only the 'done/error' qualification for early return, which is marginal beyond the schema's own text.

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 action (sleep for N seconds, max 600, then return) plus a conditional behavior (early return on done/error when job_id is given). It clearly distinguishes itself from get_job by naming it as the busy-loop alternative.

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 names the intended use case (polling pull_model/run_local_agent) and the alternative it replaces (busy-looping get_job), giving the agent a concrete condition for choosing this tool.

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