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 side effects: setting status in working-memory and clearing the active-task pointer. It omits what happens if the task is not active, whether the operation is reversible, permission requirements, and error behavior, so the disclosure is partial.

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 that front-load the action and then enumerate side effects; 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 mutation tool with no annotations, no output schema, and partial parameter documentation, the description is adequate on side effects but silent on failure modes, reversibility, and the reason parameter's effect, leaving real 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 coverage is only 33% — only 'reason' is documented. The description adds no meaning for agent_id, task_id, or reason, and does not compensate for the undocumented required parameters, leaving the schema and description jointly incomplete.

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 (mark an active task as abandoned) and names the two concrete side effects, which is more than a restatement of the name. However, it never differentiates itself from closely-named siblings like close_agent_task or agent_dry_run_close_task, so an agent must infer why 'abandon' is distinct from 'close'.

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 'active task' implies the precondition, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as close_agent_task. Usage is only implied.

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

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

With no annotations, the description carries the full burden. It does disclose the null-return behavior, which is genuinely useful for callers, but says nothing about whether this is a read-only operation, permissions required, or whether 'active' has a specific lifecycle state in the agent state machine.

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 null case is stated up front alongside the primary behavior.

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

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

No output schema exists, so the description is the only place return shape can be conveyed; naming 'task metadata' plus null is a reasonable start but does not say what fields the metadata contains or how 'active' is determined. Adequate but with clear gaps for a state-inspection tool.

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

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

One parameter at 0% schema description coverage, so the description should compensate more than it does; 'for an agent' only loosely identifies agent_id. It adds no format, ID-style, or validity details beyond the schema's bare string 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 and resource: returns the current active task metadata for an agent. It also declares the null fallback, which sharpens the contract. It does not distinguish itself from near-siblings like agent_status or load_agent_context, 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 mention of alternatives despite a crowded sibling set (agent_status, load_agent_context, agent_start_task). The only usage signal is inference from the tool name.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the write is an append (not an overwrite) and that entries are timestamped, plus the active-task precondition. It omits what happens on failure, whether the memory file is created if absent, and any permission requirements, so it is not fully transparent.

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

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

Two short sentences, front-loaded with the action and followed immediately by the precondition. No filler and nothing 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 simple append tool with no output schema and no annotations, the description covers purpose and precondition but leaves failure behavior, return value, and the undocumented agent_id parameter unaddressed. Adequate but with visible 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 coverage is only 67% and the description adds no parameter-level meaning at all. The task_id and entry fields are documented in the schema, but agent_id has no description anywhere, and the description never explains how the entry text is scoped or formatted.

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 (append) and resource (timestamped state entry in the active working-memory file), which clearly separates it from siblings like append_repo_progress or write_repo_task_log. It does not explicitly name those alternatives, so it stops short of a 5.

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

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

The precondition 'Requires an active task' gives a usable trigger condition, which is more than nothing. However, it never says when to prefer this over sibling state tools (agent_verify_state, agent_repair_state, agent_trace) or what to do when no task is active.

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 well: it discloses the return contents (allowed/rejected ops, bus publications, file writes) and that nothing is executed. It does not mention auth requirements or any limits, leaving some behavioral 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 tight sentences, front-loaded with the operation and its return shape, with zero 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?

The return shape is well described and there is no output schema, which helps, but with eight undocumented parameters the definition leaves the agent guessing about how to construct the payload it is meant to validate.

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?

Eight parameters at 0% schema description coverage, and the description explains none of them — gotcha, rewrites, hotUpdate, discoveries, escalations, taskLogEntry are all opaque. This is a significant gap the description fails to compensate for.

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

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

States a specific verb ('dry-run') and resource ('close-task operation') and immediately clarifies it returns a write plan without executing. This distinguishes it from the sibling close_agent_task and dry_run_close_repo_task by making the no-side-effect scope explicit.

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

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

Gives clear context — validate a payload before committing — which implies when to prefer this over the real close operation. No explicit exclusions or named alternative, but the use case is unambiguous.

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

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

With no annotations, the description carries the full burden. It usefully discloses that this is a mutation which 'rebuilds or clears the active-task pointer' and that it is attempted only when safe, but it omits what state is destroyed by clearing, required permissions, reversibility, and behavior on 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 tight sentences with the action front-loaded and the scoping constraint immediately after. No filler 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 mutation tool with no annotations, no output schema, and undocumented parameters, the description covers the core action but leaves preconditions, failure modes, and result semantics unaddressed. Adequate minimum, 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?

One parameter (agent_id) at 0% schema description coverage, so the description must compensate and does not — it never mentions agent_id or which agent's state is targeted. The parameter name is largely self-explanatory, limiting the damage, but no added meaning is provided.

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 (repair) plus resource (agent task lifecycle state) and narrows scope to the active-task pointer. It is distinguishable from siblings like agent_verify_state and agent_append_task_state, though it never names them directly.

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

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

The phrase 'when it can do so safely' implies a conditional context for invocation, but the description never says when to use this instead of agent_verify_state, agent_append_task_state, or agent_abandon_task. No prerequisites or exclusions are given.

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

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

With no annotations, the description carries the full burden and does disclose meaningful mutation behavior: it creates a working-memory file and mutates an active-task.md pointer, plus what it returns. It stops short of noting permissions, overwrite semantics if a task already exists, or failure modes.

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

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

Three short sentences, zero waste, side effects and return values front-loaded after the purpose statement. Nothing could be cut without losing information.

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

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

For a mutation tool with no annotations and no output schema, the description supplies the key behavioral facts (files created, pointer set, taskId/paths returned) an agent needs before invoking it. Missing only prerequisite/error handling detail, which is minor here.

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 (including optional project, task_id override, and description) are already documented in the schema. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Start a new task for an agent') and names the concrete side effects (working-memory file, active-task.md pointer) and return values. It implicitly contrasts with siblings like close_agent_task and agent_abandon_task, but never names them 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 context is implied — you call this before doing task work — but there is no explicit when/when-not guidance and no mention of alternatives such as agent_active_task or close_agent_task. Adequate minimum without routing help.

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 does disclose the content of the response (active task, verification issues, close policy, traces), which implies a non-mutating read, but it says nothing about permissions, cost, truncation, or side effects.

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 names the tool's domain first and then enumerates its payload areas. Every clause carries information; nothing is padding.

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

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

With no output schema, the description must characterize the return, and it does so at a coarse level, but it leaves the required agent_id unexplained, doesn't clarify the limit's effect, and omits any behavioral or failure-mode context. Adequate minimum but with clear gaps for a two-parameter status tool.

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

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

Schema description coverage is only 50%: the limit parameter is documented in the schema, but the required agent_id is bare. The description mentions neither parameter nor explains how limit interacts with the 'recent runtime traces' it advertises, so it fails to compensate for the coverage gap.

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

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

States a specific verb (Return) and resource (agent lifecycle status), then enumerates the four payload areas, which distinguishes it from narrower siblings like agent_active_task, agent_verify_state, and agent_trace. It reads as an aggregate status read rather than a mutation, but it does not explicitly contrast itself with those siblings.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent must infer from the sibling list that this aggregates what agent_active_task, agent_verify_state, and agent_trace return individually.

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 the data source and that traces include rejected writes, but says nothing about ordering guarantees, whether results are bounded by log rotation, or any access requirements for reading agent-runtime.log.

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 dense sentences with zero filler; the core action and data source lead, with the use case following. 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 3-param, no-annotation, no-output-schema tool this is only modestly complete: the agent learns what is returned and why, but not the shape of a trace entry, ordering, or how limit interacts with recency—information that has nowhere else to live.

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%; the description's naming of 'context loads and close-task writes' loosely maps to the type enum and 'recent' hints at the limit's temporal role, but it does not explain the enum values' semantics or the default limit behavior beyond what the schema already states.

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

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

Names a specific verb (Return), resource (recent runtime traces), scope (for an agent), and even the backing log file, with parenthetical detail on what a trace contains. It is clearly distinct from siblings like agent_status or read_index, though it never explicitly contrasts 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?

The second sentence supplies use cases ('debugging context budget issues and rejected writes'), which implies when the tool is appropriate. However there is no guidance on when NOT to use it, nor a named alternative for adjacent tasks such as checking current state.

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

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

With no annotations, the description carries the full burden. 'Verify' and 'Detects' imply a read-only diagnostic, and naming the concrete failure modes adds real value beyond what the schema provides. However, it does not confirm it is non-mutating, does not describe what gets reported, and says nothing about permissions.

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

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

Two tight sentences, front-loaded with the core verb and resource, with no filler. Size is well matched to a single-parameter verification tool.

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

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

For a one-parameter verify tool with no output schema and no annotations, the agent learns what is checked but not what the result looks like, whether it is read-only, or how it relates to repair/status siblings. 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 0% and the single parameter (agent_id) is never mentioned in the description; only the vague phrase 'for an agent' hints at it. With low coverage the description should compensate but does not, so it adds essentially nothing over the bare schema property name.

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

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

States a specific verb ('Verify') plus a precise resource ('task lifecycle consistency for an agent'), and the second sentence enumerates exactly what it looks for (broken active-task pointers, orphan working-memory files). This clearly separates it from mutations like agent_repair_state, though it never explicitly contrasts itself with the adjacent agent_status/agent_active_task tools.

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

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

The description implies a diagnostic use case but never states when to reach for this tool versus agent_status, agent_active_task, or agent_repair_state. No prerequisites, no alternatives, no conditions that select it. The detection clause hints at intent but leaves routing entirely to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Append' implies additive, non-destructive mutation, but it does not say whether the target file/directory is created if missing, whether entries are deduplicated or ordered, what permissions are needed, or what the response 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?

A single tight sentence with the target path front-and-center and no filler. It is concise but arguably under-specified rather than optimally structured.

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

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

For a 3-parameter mutation tool with zero annotation coverage, no output schema, and 33% schema description coverage, the description is too thin. It omits the meaning of required params, write behavior on missing files, and any return/error semantics an agent would need.

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

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

Schema description coverage is only 33% (only agent_id is documented), and the description adds nothing about the two required parameters 'repo' and 'entry' — e.g. expected format, length, or whether entry supports markdown. It fails to compensate for the coverage gap.

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

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

States a specific verb (append) and resource (progress entry in wiki/repos/<repo>/progress.md), so an agent knows exactly what the call does. It does not differentiate itself from nearby siblings like write_repo_task_log or agent_append_task_state, which also write progress-like data.

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

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

There is no guidance on when to use this versus write_repo_task_log, agent_append_task_state, or sync_repo_markdown, all of which operate in the same repo/progress space. No prerequisites or context for invocation are given.

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

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

No annotations are present, so the description carries the full burden, and it does disclose a genuinely non-obvious trait: the writeback is atomic and any forbidden write aborts the whole commit. It still does not say what counts as 'forbidden', what permissions are needed, or what the tool returns on success/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 tightly packed sentences with no waste; the transactional nature and the effect list are both front-loaded, and the atomicity caveat ends the description on the operative constraint.

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 multi-write mutation tool with no annotations and no output schema, the description covers the effect set and the all-or-nothing failure semantics well. It falls short only on parameter formats and on disambiguating itself from the dry-run and repo-level close siblings.

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

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

With 0% schema coverage over 8 params, the description must carry the burden. It maps six params to concepts (task log entry, hot update, gotcha, discoveries, escalations, rewrites), but leaves agent_id and project unmentioned and gives no format, type, or ordering detail for any of them.

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 ('Transactional end-of-task writeback for an agent') and enumerates the concrete effects (appends task log, updates hot, writes gotchas, publishes discoveries/escalations, creates rewrites). It does not differentiate itself from nearby siblings such as agent_dry_run_close_task, dry_run_close_repo_task, or close_repo_task, so an agent must infer which close variant to 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?

The phrase 'end-of-task writeback' implies the usage context, but there is no explicit when-to-use, when-not-to-use, or naming of the obvious alternate (agent_dry_run_close_task / agent_abandon_task). Guidance is implied rather than stated.

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

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 atomicity/transactionality and the set of side effects that occur. It does not say whether writes are reversible, what authorization is needed, what happens on partial failure, or what the response returns.

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

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

Two compact sentences; the core purpose ('transactional end-of-task writeback') is front-loaded and the list of effects follows efficiently. Dense but not bloated.

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 9-parameter mutation with no annotations and no output schema, the description covers the major side effects but not the parameter grammar or the relationship to the dry-run sibling. Workable for an experienced agent, incomplete for a new 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 coverage is 0% across 9 parameters, so the description must compensate. It maps meaning onto several fields (gotchas, hotUpdate, taskLogEntry/progress, discoveries, escalations, rewrites), which is genuinely helpful, but leaves repo, project, agent_id and the array element shapes unexplained.

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 purpose: an end-of-task writeback that performs several named effects (progress, hot memory, gotchas, discoveries/escalations, rewrites) atomically. It is more informative than a bare verb+resource, though it never explicitly distinguishes itself from the near-namesake sibling dry_run_close_repo_task.

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

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

The phrase 'end-of-task writeback' implies the moment to call it, which is reasonable usage context. However, it names no alternatives or preconditions — nothing tells the agent when to prefer this over dry_run_close_repo_task or close_agent_task, both of which are 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?

No annotations are provided, so the description carries the full burden. It discloses that compilation uses Claude (implying LLM cost/latency) and that 'full' recompiles everything, but it never states whether existing wiki pages are overwritten, whether the operation is reversible, or what happens on partial 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 tight sentences with the core action front-loaded and mode guidance condensed into one clause. The mode sentence partly duplicates the schema description, which is a minor redundancy but not wasteful.

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 action and the mode switch but omits the PIN authentication requirement described only in the schema, and says nothing about output or the fate of existing pages. 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 coverage is 100%, so both parameters are already documented in the schema, including the enum values and default. The description's restatement of mode semantics adds no information beyond the schema, 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 and resource: processing raw documents and compiling them into structured wiki pages. The action is distinct from siblings like lint_wiki or search_wiki, though the description never names or contrasts those alternatives 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 implied by the mode explanation ('new docs only' default vs 'full' recompile), which tells the agent which mode to pick but not when to invoke this tool at all versus sibling tools like lint_wiki. No when-not conditions or prerequisites (e.g. PIN) are stated as 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 it does disclose the single most important behavioral trait: nothing is executed and a full write plan is returned. It omits auth requirements and whether the plan output format matters, but the safety profile is clear and non-contradictory.

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, the resource, and the key constraint with zero waste.

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 conveys the essential contract (plan returned, no writes) and, with no output schema, the return value is at least characterized conceptually. But nine undocumented parameters and no annotations leave real gaps for a tool whose inputs likely mirror close_repo_task.

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

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

Nine parameters at 0% schema description coverage and the description mentions none of them, not even the required repo or agent_id. An agent must guess what gotcha, rewrites, hotUpdate, discoveries, escalations, or taskLogEntry mean, so the description fails to compensate for the schema gap.

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

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

States a specific verb (dry-run) and resource (repo close-task operation) and defines the outcome: a write plan with no writes executed. It distinguishes itself from close_repo_task by implication, though it never names the executing sibling.

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 preview-before-commit use case ('without executing any writes'), which is enough for an agent to infer it precedes close_repo_task. However, no explicit when-to-use/when-not guidance or named alternative is provided.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no indication of what the "overview" contains, whether it is read-only, whether it requires the repo to be tracked/registered, or how errors surface. Only the word "Get" hints at a read operation.

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

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

A single tight sentence with no filler, appropriately front-loaded. It is efficient, though its brevity comes at the cost of the missing details noted elsewhere rather than being a structural flaw.

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

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

For a one-parameter lookup with no output schema and no annotations, the description should at least clarify the repo identifier and what the returned overview comprises. Neither is covered, so an agent cannot reliably call or interpret this tool.

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

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

Schema description coverage is 0%, so the sole required parameter "repo" is undocumented in both the schema and the description. The description does not say whether repo is a name, ID, slug, or path, leaving the agent to guess the identifier 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?

It gives a recognizable verb ("Get") and resource ("home page and overview"), but "home page" is ambiguous for an agent and the description never distinguishes this from siblings like read_index, load_repo_context, or search_repo_docs. The purpose is inferable but not sharply defined.

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 the many competing repo-context tools (load_repo_context, read_index, search_repo_docs). No prerequisites, no exclusions, no alternatives named.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the key side effect that it 'Writes a lint-report.md to the wiki' rather than being a pure read. However, it omits anything about permissions/PIN auth, whether an existing report is overwritten, or resource/time cost.

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: the action and detection scope come first, the write side effect second. No filler 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 mutating tool with no annotations and no output schema, the description covers the action, findings, and the report artifact, but leaves auth requirements and overwrite behavior 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?

Only one parameter exists and the schema already documents it at 100% coverage ('PIN required if PRIVATE_PIN is set'). The description adds nothing about the pin or auth flow, so the baseline 3 for high schema coverage 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 ('run a health check') and resource ('the wiki'), then enumerates exactly what is detected (contradictions, orphans, stale content, knowledge gaps). No sibling tool performs linting, so the agent can identify it unambiguously.

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 what the check finds but never says when an agent should run it versus other tools like read_index, search_wiki, or compile_wiki, nor any prerequisites. Usage is only implied by the 'health check' framing.

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 conveys that this is a listing operation, but says nothing about ordering, pagination, result limits, or whether the caller needs any particular auth or channel membership.

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

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

A single efficient sentence with the resource front-loaded and the optional filter trailing. Nothing is wasted, though the brevity is partly under-specification rather than pure conciseness.

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

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

For a simple two-parameter list tool with no annotations and no output schema, the definition covers the essentials but omits return-shape hints, ordering/pagination behavior, and differentiation from the near-identical repo sibling. Adequate as a minimum-viable definition, not more.

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

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

Schema description coverage is 0%, so the description has to compensate. It does clarify that 'channel' selects the bus channel and that 'status' is an optional filter, which is more than the bare schema types convey, but it gives no accepted status values or channel 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 clear verb plus resource ('List items in a bus channel'), so the agent knows what it does. However, it does not distinguish itself from sibling list_repo_bus_items or explain the agent-vs-repo scope split, so the agent must open the schema 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?

The description notes an optional status filter but gives no when-to-use context, no prerequisites, and no indication of when to prefer this over list_repo_bus_items or query_wiki. Usage is left entirely to inference.

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

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

With no annotations, the description carries the full disclosure burden. 'List' strongly implies a read-only, non-destructive operation, which is the main behavioral fact an agent needs, but it says nothing about scope limits, pagination, or whether an empty vault returns an empty result.

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

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

A single short sentence with the verb and scope front-loaded and no wasted words. Appropriately sized for a zero-argument list operation.

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

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

For a trivial parameterless list tool this is close to sufficient, but with no output schema the description could have stated what a returned 'agent contract' looks like or the shape of the listing. It leaves the result format undefined.

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 clarify beyond what the schema shows. Baseline 4 applies for a parameterless 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 a specific resource ('agent contracts in the vault'), which distinguishes it from the similarly named sibling list_agent_bus_items. However, it offers no further differentiation among the many other list_* siblings beyond the resource noun.

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

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

The description gives no guidance on when to use this tool versus alternatives such as list_agent_bus_items or agent_status, and no prerequisites or context are stated. Usage must be inferred entirely from the name.

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

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

With no annotations provided, the description carries the full behavioral burden and discloses almost nothing. It does not state that the operation is read-only, whether results are paginated or ordered, whether it returns article titles/IDs or full content, or what happens for an empty section.

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

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

A single short sentence with zero filler, front-loading the verb and resource. Nothing in it is redundant or padding.

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

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

For a one-argument, enum-driven read tool this is close to sufficient, and the schema fully documents the parameter. However, with no output schema and no annotations, the description leaves open what a result looks like and what the operation's side effects (none?) are, which keeps it at minimum-viable rather than 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 description coverage is 100% and the sole parameter is an enum with nine self-explanatory values, so the schema does the heavy lifting. The description's phrase 'specific wiki section' only restates the parameter rather than adding format or constraint detail, 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 ('List') and resource ('articles') with a scoping qualifier ('in a specific wiki section'), which is enough to distinguish it from mutating siblings like compile_wiki or promote_learning. It does not explicitly differentiate itself from read_index or search_wiki, which are the closest 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?

Usage is only implied by the purpose: an agent can infer this is the tool to enumerate articles within one section. There is no statement of when to prefer it over search_wiki (keyword lookup) or read_index (index browsing), and no exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. 'List' implies a safe read, but nothing is said about filtering semantics, the limit parameter's default/max, ordering, pagination, or whether status filtering changes the result set.

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

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

A single compact sentence with the resource front-loaded. Efficient, though the trailing parenthetical duplicates schema enum values rather than adding 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 4-parameter tool with no annotations, no output schema, and zero schema description coverage, the definition is too thin. An agent cannot determine default result size, status semantics, or return shape from this description.

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

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

Schema coverage is 0% and there are 4 parameters. The description reproduces the channel enum values that already exist in the schema, but says nothing about repo, limit, or status — the three parameters that actually need explanation.

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

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

Names a specific verb (List) and resource (bus items) scoped to a repo channel, and enumerates the channel values. It does not differentiate itself from the sibling list_agent_bus_items or explain how the two listings differ, so it falls short of a 5.

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

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

No statement of when to use this versus list_agent_bus_items, list_repo_bus_items' counterparts like publish_bus_item, or any workflow context. The channel list hints at the domain but gives no selection guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the output includes sync status and doc counts—useful context about the return shape—but says nothing about permissions, pagination, ordering, or whether the result set is bounded. For a read-only listing tool this is some value, but not rich behavioral context.

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

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

A single, front-loaded sentence that covers the action, resource, and returned information without any filler. Every word earns its place.

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

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

For a simple repository-listing tool with one optional parameter and no output schema, the description is minimally adequate: it names the resource and two returned fields. However, it omits that results can be filtered by status, gives no sense of pagination or result limits, and says 'all' without qualification, leaving a few gaps an agent must resolve by inspecting 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 single optional status enum with its 'Filter by status' description is fully documented in the schema. The tool description adds nothing about filtering—indeed it says 'List all', which is slightly at odds with the existence of a filter—so the baseline of 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?

The description states a specific verb ('List') and resource ('tracked repos') and even notes the returned fields ('sync status and doc counts'). It does not explicitly differentiate from any sibling tool, but no sibling appears to list repos, so the purpose is clear. The one missing piece for a 5 is an explicit contrast with 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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as get_repo_home or search_repo_docs. The intended usage is only implied by the verb 'List' and the scope 'tracked repos'.

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 hints at contract enforcement (tier, budget, allowed reads) and scoping, but does not state side effects, permissions, failure behavior, or return characteristics.

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

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

One front-loaded sentence with no filler. The core action and its scoping constraint 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 2-parameter tool with no annotations and no output schema, the description is too sparse. It does not explain what the returned context bundle contains, how contract violations manifest, or how project and agent_id interact.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It only indirectly implies that agent_id refers to an agent; it says nothing about what project means, whether it is optional, or how either parameter affects the loaded bundle.

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 (Load) and resource (scoped context bundle for an agent), and adds the contract constraint. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling load_repo_context.

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 use when an agent needs a context bundle, but gives no when-to-use guidance, no when-not-to-use guidance, and does not name or contrast with alternatives such as load_repo_context.

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

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

No annotations exist, so the description bears full behavioral burden. 'Prioritized bundle' hints that budget_bytes controls selection/truncation, but nothing is said about read-only nature, side effects, permissions, or what the bundle contains.

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

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

A single front-loaded sentence with no waste, but its brevity comes at the cost of under-specification rather than tightness.

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

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

No annotations, no output schema, and three parameters at 0% description coverage. For a tool that produces a 'prioritized bundle', the description omits what gets prioritized, how budget is applied, and how agent_id affects results.

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

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

With 0% schema coverage and three undocumented parameters, the description must carry the load, but it only names 'repo'. It never explains agent_id or what budget_bytes does (byte budget, prioritization/truncation behavior, default of 50000).

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 ('Load') and resource ('prioritized context bundle') scoped to a repo. It is clear enough to distinguish from generic wiki readers, though it never explicitly contrasts itself with the near-identical sibling load_agent_context.

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

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

The only guidance is the implied 'for an agent working on a specific repo'. There is no statement of when to prefer this over load_agent_context, or when a plain repo read (get_repo_home, read_index) would suffice.

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 previous canonical is snapshotted, that the new document is written with provenance, and that the rewrite state transitions to merged. It still omits failure behavior on tier/approved checks and whether the merge is reversible beyond the snapshot.

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

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

Three short sentences, front-loaded with the action, then side effects, then preconditions. Every clause earns its place with no repetition of schema 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?

For a mutation tool with no annotations and no output schema, the description covers the action, side effects, state transition, and preconditions adequately. It stops short of explaining supersedes/force interaction or the result of a failed merge, which are the remaining 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 100%, so all seven parameters (including force and supersedes) are already documented in structured form. The description adds only the approved-state and approver-tier constraints, which map to rewrite_path and approver, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Merge an approved rewrite artifact into the canonical project document.' This clearly separates it from write_rewrite_artifact (which creates the artifact) and from the read/search siblings, so an agent can pick it without opening the schema.

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

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

It gives two hard preconditions for use ('rewrite must be in approved state' and 'approver must meet minimum tier'), which implies the context in which the tool is callable. However, it never names an alternative (e.g. write_rewrite_artifact) or states when not to merge, so the when/when-not routing is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It discloses one side effect (marks source as promoted) but says nothing about the required approver's role, whether promotion is reversible, permission/auth needs, or what 'provenance' actually records. For a mutation tool this leaves major 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?

A single compact sentence front-loads the core action and appends the side effect, with no filler. It is efficiently sized, though it is arguably under-specified rather than optimally structured.

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

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

A mutation tool with no annotations, no output schema, four undocumented parameters (three required), and an unaddressed sibling (promote_repo_learning) is inadequately covered. An agent cannot confidently supply channel/approver or predict the promotion's consequences from this text.

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

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

All 4 parameters have 0% schema description coverage, so the description must compensate. It only loosely implies 'target' (target knowledge location) and 'id' (bus item), while giving no meaning for 'channel' or 'approver', which are both required. The required approver gate is especially important and unexplained.

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 (promote) and resource (bus item) moving to a target knowledge location, which is reasonably distinct from the sibling promote_repo_learning's repo scope. However it never names that sibling to disambiguate the two, so differentiation is inferable rather than explicit.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as publish_bus_item or promote_repo_learning. The agent must guess when promotion is appropriate versus publishing or syncing. No exclusions or context provided.

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 implies a mutation ('promote') but says nothing about whether the operation is reversible, what permissions the required 'approver' implies, or what side effects occur on the source item. The mention of 'provenance' hints at metadata being recorded but is too thin to count as disclosure.

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

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

A single sentence with no filler, which is structurally clean, but its brevity is under-specification rather than earned conciseness given the complexity of the operation.

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

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

For a mutation tool with no annotations, no output schema, and five undocumented parameters, this description is far too sparse. An agent cannot reliably invoke it without guessing at parameter meanings and the approval model.

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?

Five parameters with 0% schema description coverage, and the description explains none of them. The key question of what 'channel', 'approver', and 'target_path' mean or how they interact is left entirely unanswered.

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

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

The description states a verb ('Promote') and a resource ('a repo bus item') with a destination of sorts ('canonical or learned location'), which is more than a tautology but still vague about what a 'repo bus item' or 'canonical/learned location' actually is. It does not distinguish itself from the sibling promote_learning, which an agent would have to disambiguate on its own.

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

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

There is no when-to-use guidance, no preconditions, and no mention of the closely named sibling promote_learning or how the two differ. The agent is left to 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?

With no annotations, the description carries the full behavioral burden. 'Publish' implies a write, but nothing is said about append-only semantics, whether the item is immutable, who reads the channel, or what happens on failure. Six parameters and a mutation with zero behavioral disclosure is a significant gap.

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

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

A single front-loaded sentence with no filler, which is structurally clean. But for a six-parameter tool with no schema coverage, this level of brevity is under-specification rather than true conciseness.

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

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

No annotations, no output schema, and 0% schema description coverage mean the description is the only source of information, and it covers one sentence. It is not complete enough for an agent to call a six-parameter write operation correctly.

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

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

Schema description coverage is 0%, so the description must compensate and does not. It only hints at valid values for 'channel'; the meaning and format of 'from', 'to', 'body', 'project', and 'from_tier' are left entirely undefined.

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

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

States a specific verb (publish) and resource (bus item/channel) and enumerates the channel values, which lets an agent recognize the tool. However, it never clarifies that this is the agent bus rather than the repo bus, leaving it ambiguous against publish_repo_discovery and publish_repo_escalation, whose names overlap with two of the listed channels.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling alternatives (publish_repo_discovery, publish_repo_escalation) that an agent must choose between. Usage is only weakly implied by the channel enumeration.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about permissions required, whether publishing is idempotent or append-only, what happens on duplicate publishes, or what the call returns. The only behavioral hint is the target path, which indicates where content lands.

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

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

One sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though efficiency here partly reflects under-specification rather than disciplined editing.

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?

This is a mutation tool with no annotations, no output schema, and four undocumented parameters, so the description should be doing far more work than it is. An agent cannot confidently determine argument formats, side effects, or failure modes.

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

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

Schema description coverage is 0% for four parameters (repo, from, body, project), and the description only partially implies 'repo' via the path template. 'from', 'body', and 'project' have no meaning attached anywhere, so an agent must guess their formats and roles.

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 (Publish) and resource (a discovery bus item) and even names the target path, which tells an agent this writes into a repo-scoped discovery bus. It does not distinguish itself from siblings like publish_bus_item or publish_repo_escalation, so it falls short of a 5.

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

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

There is no statement of when to use this tool versus publish_bus_item, publish_repo_escalation, or promote_repo_learning, nor any prerequisites or exclusions. The destination path implies a scope but gives no routing guidance.

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

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

With no annotations, the description carries the full burden. It says 'publish' (implying a write) and gives the target path, but discloses nothing about permissions, side effects, whether the write is idempotent, or what happens on failure. For a mutation tool with zero annotation coverage this is a significant gap.

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

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

A single efficient sentence with the destination front-loaded and no wasted words. It is concise, though the brevity reflects under-specification rather than deliberate 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?

A mutation tool with no annotations, no output schema, and 0% parameter documentation leaves the agent without the permission, return-value, or field-level context needed to call it correctly. The description does not compensate.

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

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

Schema description coverage is 0%, so all four parameters (repo, from, to, body) are undocumented in both the schema and the description. The <repo> placeholder loosely maps to the repo param, but 'from', 'to', and 'body' receive no explanation at all.

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

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

Names a specific verb (publish) and resource (escalation bus item) plus the exact destination path wiki/repos/<repo>/bus/escalation/, which distinguishes it from generic publish_bus_item and publish_repo_discovery. It does not explicitly explain the difference from those siblings, but the 'escalation' scope is clear.

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

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

No guidance on when to publish an escalation versus the sibling publish_bus_item or publish_repo_discovery, and no prerequisites or conditions are stated. The agent must infer usage purely from the tool name.

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

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

No annotations are provided, so the description carries the burden. It discloses the return behavior (synthesized answer with citations), which is useful, but says nothing about permissions, rate limits, or cost. The PIN/scope access requirements are only covered by the schema, not the description.

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-loaded with the action and resource and immediately followed by the return shape. No filler words 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 single-question Q&A tool with full schema coverage, the description covers what it does and what it returns. With no annotations, a brief note that it is a read-only query would have closed the remaining gap, but the tool is otherwise adequately described.

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 parameters are fully documented in the schema; the description adds no syntax or format detail beyond it. The baseline of 3 applies when the schema already 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 (ask a question) and resource (KB) plus the engine, and the phrase 'synthesized answer with citations' implicitly separates it from siblings like search_wiki that return raw documents. It stops short of naming the alternative explicitly, so it is clear but not maximally differentiated.

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: reach for this when you want a synthesized answer rather than retrieved documents, contrasting with search_wiki/read_article. No explicit when-to-use, when-not-to-use, or named alternative is given, so guidance is inferred rather than stated.

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

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

With no annotations, the description carries the full burden, and it does disclose one meaningful prerequisite: private articles require a pin. However, it says nothing about behavior on a missing slug, whether reads are side-effect-free, or what content is returned.

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

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

A single front-loaded sentence pairing the action with its key and a concrete example, with the pin caveat appended. 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 simple read-by-key tool with a fully documented two-parameter schema and no output schema, the description covers purpose, key format, and the one access precondition. Only edge-case behavior is left unstated.

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

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

Schema description coverage is 100%, so both slug and pin are already documented in the schema, including the PIN env-var match requirement. The description's slug example and pin mention restate rather than extend 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 ('Read the full content of a wiki article') plus the lookup key (slug), which cleanly separates it from search_wiki/list_articles/read_index. It does not explicitly name a sibling, but the verb+resource is unambiguous.

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

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

No statement of when to use this versus search_wiki, query_wiki, or read_index, and no mention of failure modes. The only usage-adjacent note is the pin prerequisite for private articles.

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, but the description's 'Read' verb makes the read-only, non-mutating nature clear and states what the file contains. For a zero-parameter local index read, no auth, rate-limit, or destructive-behavior disclosure is really needed, so the modest gap is acceptable rather than severe.

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 and its contents, and zero wasted words. Nothing to trim.

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 trivial zero-param read tool with no output schema, the description covers the essentials. However, given that list_articles is an adjacent sibling that could plausibly serve the same need, the lack of any disambiguation leaves the definition only minimally complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no input is required.

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

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

States a specific verb (Read) and resource (wiki master index / index.md) and clarifies the returned content ('lists all articles by section'). It does not explicitly distinguish itself from the nearby sibling list_articles, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as list_articles, search_wiki, or read_article. The agent must infer from context whether reading the master index is preferable to listing or searching.

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 does not meet it. It conveys only that this is a search over three doc sources; it says nothing about ranking, result shape, permissions, or how the default limit behaves.

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 parenthetical earns its place by enumerating the searchable sources. Slightly terse for the amount of undocumented behavior it must cover.

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

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

For a 3-parameter tool with 0% schema description coverage, no annotations, and no output schema, one sentence is insufficient. The agent lacks guidance on the limit parameter, result structure, and what the three listed sources actually mean in terms of result provenance.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. 'Specific repo namespace' loosely maps to repo and 'full-text search' implies query, but the limit parameter (default 20) is never explained and no format or syntax hints are given for query or repo.

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 ('Full-text search within a specific repo namespace') and clarifies scope with the parenthetical listing canonical docs, imported docs, and bus. It gives an agent enough to distinguish it from wiki-oriented siblings like search_wiki, though it never names an alternative explicitly.

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

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

No when-to-use or when-not-to-use guidance is present. The description implies a repo-scoped search but does not tell the agent how to choose between this and search_wiki, query_wiki, or read_index.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no indication that scope="private"/"all" requires authorization (only implied by the schema), no note on result ordering, truncation, or what a match looks like. For a search tool with zero annotation coverage this is thin.

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 naming the action, the corpus, and the input. Nothing redundant and nothing that could be trimmed without losing information.

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

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

For a low-complexity, read-only search with a fully documented 4-parameter schema and no output schema, the description is minimally sufficient. It is incomplete in that it never mentions the scope/PIN access dimension or how results relate to the other wiki-reading tools.

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 scope semantics, the PIN requirement, and the limit default are already fully documented in the schema. The description adds no query syntax, matching behavior, or scope guidance beyond it, so the baseline 3 applies.

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

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

Specific verb (Search) plus resource (Agentic Engineering Knowledge Base articles) and the query-driven nature of the operation. It does not, however, distinguish itself from the sibling `query_wiki` or explain how it differs from `read_index`/`list_articles`, so an agent still has to guess which wiki-lookup tool fits.

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 and no mention of alternatives. Given three sibling tools that also surface wiki content (query_wiki, read_index, list_articles), the absence of any routing hint is a real gap.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: file-selection rules, excluded vendored directories, the exact write destination (wiki/repos/<repo>/repo-docs/), and a side effect (recording sync state in the registry). It omits whether existing docs are overwritten or merged, idempotency/rate-limit behavior, and error handling, 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?

A single front-loaded sentence that leads with the verb and resource, with the detailed path/exclusion lists packed into a parenthetical. Information-dense and mostly earning its place, though the parenthetical is heavy enough to slightly hinder scanning.

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 what is fetched, what is skipped, where output goes, and that registry state is updated. It is fairly complete, with the main remaining gaps being overwrite semantics and repo identifier format.

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%: the token parameter is documented in the schema, but repo is bare. The description only implies that repo identifies a GitHub repository and never specifies the expected format (e.g., owner/name), so it fails to compensate for the coverage gap.

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

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

The description states a specific verb (sync) and resource (repository markdown docs from GitHub) and enumerates exactly what is fetched (.md/.mdx files, README/CLAUDE.md, docs/, specs/, plans/, reports/, architecture/) and where it lands. It is immediately distinguishable from read/search/compile siblings, which operate on the wiki rather than pulling from GitHub.

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 infers you call this to pull a repo's markdown into the wiki, but there is no explicit when-to-use, no prerequisites (e.g., repo access, prior repo registration), and no mention of alternatives such as search_repo_docs or load_repo_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 behavioral burden, and it only implies append semantics via the verb. It does not say whether entries are immutable, whether the task log is per-repo or per-agent, whether auth/agent registration is required, or what happens on duplicate entries.

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

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

A single tight sentence with the verb and resource front-loaded; nothing is wasted. It is arguably too terse given the surrounding ambiguity, but it is structurally 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?

This is a mutation tool with no annotations, no output schema, 25% schema coverage, and several overlapping siblings. The definition leaves an agent unable to determine call prerequisites, uniqueness behavior, or how it differs from append_repo_progress.

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 25% (only task_id is described), and the description adds nothing about repo, agent_id, or entry beyond restating the sentence. The three required parameters remain semantically opaque, so the description fails to compensate for the low coverage.

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

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

States a concrete verb (append) and resource (task log entry tied to a repo and agent), which is clearer than most siblings. However, it never distinguishes itself from nearby tools like append_repo_progress or agent_append_task_state, so an agent has no explicit signal for when this log differs from progress or task-state append operations.

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

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

There is no guidance on when to use this tool versus append_repo_progress, agent_append_task_state, or agent_trace, all of which plausibly overlap. No prerequisites (e.g., whether the agent must have a started task) are mentioned.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It discloses the creation location but does not state whether an existing artifact is overwritten, what permissions are required, whether content is validated, or what the tool returns.

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

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

The description is a single front-loaded sentence with no waste. It is appropriately concise, though the extreme brevity contributes to under-specification elsewhere rather than being a structural flaw itself.

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 five-parameter, required-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is far too sparse. It omits what a rewrite artifact contains, how content and author are used, and how this tool relates to merge_rewrite.

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

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

Schema description coverage is 0%, so the description must compensate for all five parameters. It only indirectly explains 'repo' and 'type' through the path template, leaving 'project', 'content', and 'author' entirely unclarified.

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 action and resource: 'Create a rewrite artifact.' It also gives the target path pattern, which clarifies scope. However, it does not distinguish this tool from sibling tools such as merge_rewrite, so sibling differentiation is absent.

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

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

The description offers no explicit guidance on when to use this tool versus alternatives like merge_rewrite or compile_wiki. Usage is only implied by the verb 'Create' and the artifact path, which is not sufficient for a five-parameter mutation tool.

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