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

The description discloses significant side effects: it moves the task file from `_lifecycle/review/` to `_lifecycle/done/` and appends an `approve_task` event. It also warns about the no-op behavior on v2 projects Poisson, which is a behavioral trait not captured by annotations. Since no annotations are provided, this is a strong disclosure; however, it could mention whether the operation is reversible or if the event is auditable, but those are minor omissions.

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 concise, with the core purpose in the first line, followed by a brief mechanism, a usage note, and a version-specific caveat. Every sentence delivers essential information, and the structure front-loads the primary action and transition. It avoids redundancy and is easy for an agent to parse quickly.

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

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

Given the tool's moderate complexityholde (lifecycle transition, file moves, and event logging), the description is complete for an agent to call it correctly. It covers what the tool does, when to use it, and its side effects, satisfying the requirements. The presence of an output schema (though not detailed here) and full parameter coverage in the description ensure nothing critical is missing.

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

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

Although schema coverage is 100%, the description adds meaning by explaining that `note` is an 'Optional approval note appended to the transition event' and `actor` is the 'Role code of the approver'. These details go beyond the schema's terse descriptions, explaining the purpose and default behavior. The description's mention of the lifecycle transition adds context for `task_id` as well.

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

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

The description clearly states the action ('Approve a task under review') and the lifecycle transition (`review → done`), specifying the exact resource and state change. It also differentiates from siblings like `reject_task`, `submit_task`, and `finish_task` by naming the specific state transition and the file move, making its purpose distinct.

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 explicitly states when to use: 'Typically called by ADMIN after inspecting the work,' providing a clear context. It also notes that on v2 projects it is a no-op, which is a critical conditional that prevents misuse. It does not name an alternative tool but the context is sufficient given the sibling list includes `reject_task` and `mark_human_approved`, which are implicitly alternatives.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the task is moved (a mutation), the target directory, and that any tied report file is moved alongside. However, it does not clarify side effects such as whether the task is removed from its original location, whether the operation is reversible, or what happens if the task is not actually completed.

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

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

Two tightly written sentences with no filler. The primary action and destination are front-loaded, and the secondary behavior about the report file is stated in one additional sentence.

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 provides the essential action, destination, and important pairing behavior, and an output schema exists to cover return details. It is slightly incomplete only in that it does not address the relationship to archive-related sibling tools or specify prerequisites beyond 'completed task,' but for a simple move operation this is nearly sufficient.

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

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

Schema coverage is 100%, so the schema already documents both parameters and their formats. The description adds contextual meaning about the report file being moved, but does not explain parameter semantics beyond what the input schema provides; this matches the baseline for fully covered schemas.

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 ('Archive') and resource ('a completed task'), and clearly specifies the destination (``docs/agents/log/``). It also adds the distinctive behavior of moving the associated report alongside, which helps differentiate from sibling archive tools like ``archive_to_history``.

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 'Archive a completed task' provides clear context that this is for completed tasks and names the destination. However, it does not explicitly distinguish when to use this tool versus sibling tools like ``archive_to_history`` or ``bulk_archive_to_history``, leaving the routing decision partly 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 provided, the description carries the full behavioral burden. It discloses the mutating move, that associated reports are relocated together, that the destination is an immutable date-sharded record, and how `done_date` affects the shard. It does not mention potential error cases or reversibility, but 'immutable' communicates lasting effect.

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 compact and front-loaded: the main action and destination appear first, followed by useful side-effect and date-shard details, and then the prerequisite call. Every sentence contributes essential operational information without 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 description covers prerequisites, destination path, side effects, and date-shard behavior, and an output schema exists so return values need not be documented. It could optionally mention what happens if the task is not already archived, or how it relates to bulk history archiving, but the core operational context is complete.

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

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

Schema coverage is 100%, and both parameters are already documented in the schema. The description does clarify that `done_date` overrides the UTC done-date default, but this largely echoes the schema text; it does not add substantially new meaning for `task_id`.

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

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

The description states a specific action verb ('Move') with an explicit source (`_lifecycle/archive/`) and destination (`history/YYYY-MM-DD/<task-stem>/`), and clarifies that the task and its reports move together. This clearly distinguishes it from `archive_task`, which is explicitly mentioned as the prerequisite step, and from the bulk sibling `bulk_archive_to_history`.

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 clear context: the task must already be closed and in `_lifecycle/archive/`, and it instructs the agent to call `archive_task` first. It does not explicitly contrast with `bulk_archive_to_history` or state when not to use the tool, so it stops short of a 5.

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

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

No annotations are present, so the description carries the full burden. It clearly states it iterates every task in `_lifecycle/archive/`, delegates to `archive_to_history`, moves tasks plus reports into `history/YYYY-MM-DD/<task-stem>/`, and auto-creates `history/`. The only mild gap is not explicitly stating whether source tasks are deleted or whether the operation is reversible, though 'migrate'/'flush' strongly implies removal.

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

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

Front-loaded with the core action and scope ('Migrate all tasks'), followed by the mechanics, use cases, and a note about auto-creation. The 'Useful when' bullets are slightly redundant with the main sentence but help an agent choose this tool quickly.

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

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

For a single-parameter bulk operation with no output schema, the description covers what, where, when, and an edge case (auto-created directory). It could mention what happens to the source directory or failure behavior, but the provided context is sufficient for selection and invocation.

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

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

Schema coverage is 100%: `done_date` is fully documented with its YYYY-MM-DD format, override behavior, and fallback to `done_at`/now. The description adds modest context by showing the destination path pattern that the parameter controls, but doesn't substantially go beyond the schema.

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

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

The description opens with a specific verb-resource statement: 'Migrate **all** tasks from `_lifecycle/archive/` into the deep history archive.' It further clarifies it is a convenience bulk wrapper around `archive_to_history`, which distinguishes it from the per-task sibling. The destination pattern `history/YYYY-MM-DD/<task-stem>/` is concrete.

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

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

The 'Useful when' bullets give two concrete scenarios: project upgrades requiring date-sharded history, and flushing after a manual archiving session. It doesn't explicitly say when *not* to use it vs. `archive_to_history`, but naming the underlying per-task function and 'convenience migration tool' makes the bulk-vs-single distinction clear.

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

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

It explicitly discloses the key side-effect boundary: it does NOT install anything)Skip. It also hints at network dependency with 'latest PyPI version (if reachable)', though it does not detail failure modes or exit behavior. Good coverage for such a simple tool.

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

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

Two short, front-loaded sentences with clear formatting. The core purpose appears first, followed by the side-effect warning and the alternative tool. No wasted words.

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

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

For a simple check tool, the description covers purpose, output, network dependency, and the related upgrade action. Everything an agent needs to decide whether to invoke this tool is present.

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

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

The schema fully describes the only parameter, lang, with a default and description. The tool description does not add significant additional meaning about parameters, so it does not exceed the baseline.

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

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

The description uses a specific verb ('compare') and a clear resource ('installed fcop-mcp version' vs 'latest on PyPI'). It also distinguishes itself from the sibling upgrade_fcop by explicitly stating it does not install.

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 clearly states what this tool does and explicitly says it does not install anything, directing agents to call upgrade_fcop instead. This provides a clear when-to-use / when-not-to-use boundary.

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 burden and does well: it discloses file movement, frontmatter mutation, and the v2 no-op behavior. It does not mention permissions, idempotency, or what happens if the task is already claimed, so not a 5.

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

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

Two tightly written sentences: the first states the core transition, the second explains the mechanism and the v2 caveat. No repeated information, no filler.

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

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

For a state-transition tool with a complete schema and output schema available, the description covers what happens, where files move, and the version exception. It could add explicit guidance on choosing this over create_task/archive_task/finish_task, but nothing essential is missing.

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

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

The input schema already documents both parameters (actor with default 'agent'; task_id with example format). The description adds no parameter-specific meaning, and with 100% schema coverage the baseline score 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?

Description uses a specific verb ('claim') and a precise resource transition ('inbox → active'), then details the concrete mechanics: moving the file from '_lifecycle/inbox/' to '_lifecycle/active/' and appending a transition event to frontmatter. This distinguishes it clearly from sibling lifecycle tools like archive_task or finish_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 v3 lifecycle framing gives clear context for when the tool applies, and the v2 no-op note gives an explicit exclusion condition. It stops short of naming sibling alternatives or stating 'use this instead of X', so it doesn't earn a 5.

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

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

With no annotations, the description carries the full burden, and it delivers: it explains what files are created, what v3 topology is produced, that fcop/shared/ is left empty for custom teams, and that existing files are archived under .fcop/migrations/. This is rich behavioral disclosure beyond the schema.

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

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

The description is long, but every section earns its place: purpose, role semantics, topology behavior, missing docs, and next steps. It is front-loaded with the core purpose and includes structured details that matter for correct invocation, though it could be slightly tightened.

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

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

Given the tool's complexity, the absence of annotations, and the presence of an output schema, the description is remarkably complete. It covers preconditions (validate first), exact filesystem effects, what is NOT created, overwrite behavior, and recommended follow-up actions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that role codes become part of task filenames and by illustrating the format, which helps the agent understand the impact of the roles parameter beyond its raw schema definition.

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

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

The first line states a precise action and resource: 'Create an FCoP project with a custom roster of roles.' This clearly distinguishes it from sibling initializers like init_solo and init_project, which create preset or solo setups.

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 explicitly tells the agent to run validate_team_config first to catch illegal role codes without writing anything, and recommends reading the closest preset as the next step. This gives actionable when-to-use guidance relative to sibling tools.

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

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It does disclose the destination path (_lifecycle/inbox/) and the implications for recipient claiming, but it does not state whether the creation is reversible, requires no permissions, or any side effects beyond placement. The description is decent but not exhaustive; a 3 is appropriate given the lack of mutation details like whether it overwrites existing tasks.

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

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

The description is front-loaded with the core action and placement, followed by a brief context paragraph. Every sentence adds value: the spec reference, the functional equivalence, and the inbox path for claiming. It is concise and well-structured with a clear separation of primary and contextual 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?

Given the complexity of a task-creation tool with 8 parameters, high schema coverage, and an output schema, the description is sufficient. It covers the key workflow (inbox placement and claim), and the schema provides parameter details. The description doesn't need to explain return values since an output schema exists. It is complete for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well, including defaults and formats. The description does not add extra meaning beyond the schema; it references the schema fields implicitly but doesn't clarify ambiguous ones like priority aliases or thread_key usage. Baseline 3 is correct since the schema does the heavy lifting.

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

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

The description clearly states that the tool creates a new task and places it in the inbox or tasks folder, with a specific verb and resource. It distinguishes itself from write_task by noting functional identity but naming difference, which helps differentiate among siblings. However, it could be more explicit about the primary use case versus write_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 description explicitly mentions that this is the canonical entry-point for task creation per spec, and functionally identical to write_task, which provides guidance on when to use this tool. It does not explicitly state when NOT to use it or mention alternatives like claim_task or list_tasks, but the context of placement and the claim_task reference imply the workflow. Lack of explicit exclusions is a minor gap.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it names the files written, the language variants, the archive location, the overwrite condition, and the reversibility guarantee. It also explains the non-destructive force=False path, which is exactly the kind of side-effect disclosure agents need.

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 well-structured and front-loaded: the first sentence states purpose, the second lists concrete artifacts, and the third explains the branching behavior. Each sentence earns its place, and there is no filler or repeated schema content.

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

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

The description plus the 100% schema coverage and existing output schema cover the essential calling context: target files, language variants, force behavior, and reversibility. It does not explicitly state prerequisites such as an initialized project or fcop.json, nor does it contrast with sibling deployment tools, but these are not critical gaps for a tool this well specified.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value for 'force' by explaining that existing files are archived under .fcop/migrations/<timestamp>/shared/ before overwrite and that force=False reports files as skipped. It does not add meaning for 'lang' or 'team', but the schema already documents those fully.

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

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

The description names a specific verb ('Deploy'), the resource ('three-layer team documentation'), and the exact files written, so there is no doubt what the tool does. It does not explicitly differentiate itself from close siblings such as 'redeploy_rules', which keeps it just below the top score.

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 intended use is implied by the purpose: deploy team role templates into shared/. However, the description never states when to choose this over alternatives like redeploy_rules, init_project, or create_custom_team, and it gives no when-not-to-use guidance. The force=True/False branching is parameter behavior, not tool-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 provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals the side effect (writes a timestamped markdown file), the target location, the audience (ADMIN), the non-destructive relationship to rule files, and the pre-initialization behavior.

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

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

The description is compact and front-loaded: it opens with the core purpose, then gives the concrete file behavior, then the governance rule, then the edge-case behavior. Every sentence adds distinct information with 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?

The tool is simple, the schema covers both parameters fully, and an output schema is present. The description supplies the operational context an agent needs to call the tool correctly: what file gets created, where, when it is appropriate, and how it behaves before project initialization.

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 `content` and `context` are already fully documented in the input schema. The description adds no additional parameter-specific meaning, which matches the baseline expectation for fully covered schemas.

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: it writes a timestamped markdown file under `.fcop/proposals/` as a proposal for ADMIN review. It also differentiates the tool from siblings by declaring it the ONLY sanctioned way for an agent to push back on rule files, which separates it from tools like write_issue or write_report.

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 explicit when-to-use context: an agent disagrees with the current FCoP protocol or wants to push back on `fcop-rules.mdc`/`fcop-protocol.mdc`. It also gives when-not-to-use guidance by forbidding direct edits to rule files, and notes that it works before `init_project`/`init_solo`, covering prerequisite edge cases.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the output artifact path (fcop/shared/INSPECTION-{date}-{NNN}-{scope}.md) and the report's Execution Block contents, including remediation commands, owner, tier priority, and rollback. It does not explicitly state whether the tool modifies project files, though the scan-and-report framing implies it is primarily read-only aside from writing the report.

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 well-organized with headers, lists, and front-loaded purpose. The fcop_check contrast comes early, the scope list is compact, and the output/report details are clearly separated. Every sentence earns its place without filler.

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

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

For a tool with 3 optional parameters, full schema descriptions, and an output schema, the description covers the purpose, the alternative tool, the scope semantics, the generated artifact path, and the report structure. Nothing essential to selecting or invoking the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value by explaining what each scope means (e.g., takeover = first-time fcop introduction with full compliance scan and 6 blind spots), which goes beyond the bare enum values in the schema. The output parameter semantics are left to the schema, but they are already well-documented there.

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

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

The description states a specific verb and resource: it scans a project for protocol compliance gaps and produces an 'inspection-as-remediation' report. It also explicitly contrasts itself with fcop_check, making it unmistakable which tool to use for deep audits versus routine checks.

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 explicitly names fcop_check as the lightweight daily alternative and positions fcop_audit as the one-time deep inspection. The four scopes (new, upgrade, takeover, auto) further specify the exact usage situations, including the recommendation to use auto.

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 full responsibility. It discloses that the tool only detects and never prevents, describes its filesystem operations (git status --porcelain, scanning TASK/REPORT/ISSUE files, reading frontmatter only), and states it never reads task bodies. This is an unusually detailed behavioral contract.

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?

Lead bold definition is immediately clear, followed by structured numbered and bulleted detail. It is longer than strictly necessary (versioning and protocol-response details add context but could be trimmed), yet nothing is redundant.

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

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

Given no annotations and one optional parameter, the description covers what the tool does, how it works at the filesystem level, and the expected follow-up workflow. The presence of an output schema relieves it of explaining return shapes, but it still omits explicit prerequisites (e.g., initialized project/repo) and a direct boundary to fcop_audit.

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

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

The schema describes the single lang parameter completely, including default 'zh' and allowed values. The tool description adds no parameter-specific detail, but the baseline 3 is appropriate because the schema coverage is 100%.

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 audit scope: 'Cross-reference git working tree + frontmatter against the FCoP ledger' and enumerates the two specific rules (0.a.1 drift and Rule 1 role impersonation). The phrase 'detection, not prevention' helps separate it from reporting/management tools. It does not explicitly differentiate itself from the sibling fcop_audit, so it misses the top score.

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

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

Provides useful context: this is a post-hoc detection audit and the protocol-mandated follow-up is an ADMIN-issued ISSUE-*. However, it never states explicitly when to choose fcop_check over fcop_audit or fcop_report; the closest is an analogy to role_occupancy in fcop_report(). This makes usage guidance implied rather than explicit.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the side effect (creates a new ALERT-*.md file), the target location (fcop/alerts/), and an access restriction (ADMIN / Governance Observer only). It does not mention permissions enforcement, overwrite behavior, or failure modes, but for a simple create-file operation the core behavior is clear.

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 short, front-loaded with the access restriction and core action, and avoids repeating schema details. Every sentence contributes either a usage condition or an output effect.

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?

Together with the schema, the description tells the agent who is authorized, when to use it, what file will be created, and where. It lacks details on idempotency/overwrite behavior or post-creation effects, but this is a minor gap for such a simple creation 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?

The schema already describes all four parameters with 100% coverage, including allowed enum values for severity and alert_type. The description adds little parameter meaning beyond the schema, so a baseline score 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?

States a precise action: 'Manually file a governance alert', and names the concrete artifact it creates: 'a new ALERT-*.md file in fcop/alerts/'. It also restricts use to ADMIN or Governance Observer, which disambiguates its role from other 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?

Explicitly tells the agent when to use it ('when you ... detect a governance gap that automated scanning has not yet captured') and who is allowed to use it. It does not name an alternative sibling tool, but the condition for use is clear enough to route an agent.

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 alerts are automatically written by fcop_check(), that each alert is a structured file (ALERT-*.md) with severity, type, and summary, which gives useful behavioral context. It does not mention any side effects (likely none since it's a read operation), but it does explain the origin and format of the data, which goes beyond just saying 'list alerts.' This is adequate given the tool is read-only in nature, though it could mention that it does not modify anything.

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 concise and well-structured. It starts with a bold, attention-grabbing headline ('ADMIN Governance Alert Inbox'), then states the core function, explains the origin of alerts, and ends with practical usage guidance. Every sentence serves a purpose: it identifies the tool, its data source, and its use case. No redundancy, and the front-loading is effective.

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 list/filter tool with three optional parameters and an output schema, the description is complete. It covers the tool's purpose, data source, file format, and usage scenario. It also implicitly explains the return value (a list of alerts with severity and type). There is no missing information that an agent would need to invoke it correctly, given the schema covers parameters and the output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining what each parameter does in context: for example, 'last_n' as a maximum count, and status/severity as filters. It does not repeat the schema descriptions verbatim; instead, it provides a summary of what the parameters achieve (e.g., filtering by severity and status), which is helpful for an agent to understand the tool's capabilities. It slightly exceeds the baseline by clarifying the semantic intent.

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

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

The description clearly identifies what the tool does: it lists governance alerts from the fcop/alerts/ directory. It states a specific verb ('List') and resource ('governance alerts'), and distinguishes itself from sibling tools like fcop_check (which detects drift) and fcop_audit (which performs audits). The phrase 'ADMIN's red dot' immediately signals its role, making it unmistakable among the many fcop 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?

The description implies when to use it: 'run this to see what governance gaps the system has surfaced, without needing to manually patrol logs.' This gives clear context and contrasts with manual patrolling, but it does not explicitly name alternatives or exclusions. However, it is clear enough that an agent would know to use this for viewing alerts rather than creating them (fcop_create_alert).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It is exceptionally transparent: it explains the two report shapes, the versions block, the drift warning behavior, the fact that no role assignment is requested in the init report, and the constraints on agent behavior while unbound. This goes well beyond a simple 'returns a report' statement.

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 long but well-structured and front-loaded: the core purpose is in the first sentence, followed by clearly separated numbered and bulleted details. The note about the deprecated unbound_report alias earns its place because it prevents confusion with older references. Every sentence adds necessary context.

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 is complete given the tool's complexity: it covers both call scenarios, the versions/drift block, the output variants, role-assignment behavior, and agent prohibitions. Since an output schema is present, detailed return-value documentation is not required. Nothing an agent needs to call fcop_report correctly is missing.

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

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

There is only one parameter, lang, and the input schema already documents it completely with 'Output language, ``zh`` or ``en``. Default: ``zh``.' Schema description coverage is 100%, so the description need not repeat parameter details. A baseline 3 is appropriate because the description adds no parameter-specific value, but none is needed.

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

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

The description opens with a specific, actionable definition: 'FCoP Rule 0 — first tool call of every new session, also the general project-status report.' It clearly distinguishes the tool from siblings by naming the two report variants (initialization and UNBOUND) and the versions/drift block, so an agent knows exactly what fcop_report does.

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

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

Usage guidance is explicit: call it first in every new session, and the description lists the exact conditions for each report type (missing fcop.json vs. initialized but no role). It also gives exclusions and guardrails, such as 'Agents must NOT invoke redeploy themselves' and prohibitions on reading task bodies or claiming roles while unbound.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the lifecycle transition, the file move, the lack of a review step, and the v2 no-op behavior. It could go further by mentioning error conditions or what happens if approval is required, but the core side effects are 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?

The description is concise and front-loaded with the key lifecycle transition. Every sentence adds value, including the v2 no-op caveat and the ADMIN approval usage note. No redundant or filler language.

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

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

Given the tool's simplicity, the output schema, and the 100% schema parameter coverage, the description is complete. It explains what happens, where files move, when to use it, and edge-case behavior on v2 projects. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the parameters task_id and actor are already fully documented. The description adds no extra meaning about either parameter, so the baseline score 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 clearly states the action: finishing an active task by moving it through the lifecycle transition active → done. It also specifies the concrete file move from _lifecycle/active/ to _lifecycle/done/, which distinguishes it from related tools like approve_task or archive_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 description provides explicit guidance: use this tool for tasks that do not require ADMIN approval, and notes that on v2 projects it is a no-op. It does not name specific alternative tools for approval-required tasks, but the context strongly implies the distinction.

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?

Since no annotations are provided, the description carries the behavioral burden, and it does so by framing the operation as non-mutating ('List') and clarifying that the team documentation is deployed during init_project rather than by this call. It doesn't discuss permissions or rate limits, but for a simple enumeration tool the transparency is adequate.

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 concise, front-loads the core action, and adds useful deployment context in a second sentence. The file names are slightly detailed but earn their place by explaining what the preset teams ship with, so no part 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?

The tool is simple, has one fully-documented optional parameter, and has an output schema, so the description does not need to explain return values. It covers what the tool lists and when to use it, which is enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the single optional lang parameter is fully documented in the schema, including its limited effect on display prose. The description adds no param-level semantics beyond the schema, so the baseline score 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 opens with 'List bundled preset teams and their role rosters,' which is a specific verb plus resource and scope. The word 'bundled' and 'preset' help distinguish this from custom-team tooling like create_custom_team, so an agent can identify the tool's purpose without opening the sibling tools.

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

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

The description clearly states a concrete trigger: 'Useful before init_project to pick a template that fits the work.' It does not enumerate exclusions or alternative tools, so it lacks an explicit when-not-to-use, but the intended context is immediately clear.

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

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

No annotations are provided, so the description is the only behavioral source. It clearly implies a read-only aggregation operation ("Return aggregate statistics"), but it doesn't explicitly state it has no side effects or that it's safe to call frequently. It also doesn't disclose any performance or rate implications. Given the read-only nature is fairly obvious from "get/summary", this is adequate but not exemplary.

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

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

Two sentences, no wasted words. The first sentence states the core purpose and output; the second adds the usage context and interpretation. The critical value-add (reconciliation with Tasks/Reviews) is front-loaded.

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

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

Given there is an output schema (not shown but declared), the description doesn't need to detail return formats. It covers what the tool returns, how to interpret it, and the action it implies. No prerequisites, parameters, or edge cases are needed. It is complete for its purpose.

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

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

There are zero parameters, and the input schema is empty (100% coverage trivially). With no parameters, the description needs to explain nothing about them. Baseline is 4, and the description adds no unnecessary parameter info, which 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 clearly states what the tool does: it returns aggregate statistics from the governance event log, specifying the three exact outputs (calls by risk level, most active tools, CRITICAL_TAG events). This distinguishes it from siblings like list_governance_events (which lists individual events) and fcop_check/fcop_audit (which probably run checks or audits).

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 explicitly says "Use as a quick health check" and explains how to interpret the results (CRITICAL_TAG events without coverage are governance gaps requiring ADMIN attention). It gives a clear when-to-use, though it doesn't explicitly mention alternatives or when not to use this tool. Still, the guidance is strong.

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 add useful output behavior, such as 'five most recent activity entries (sorted newest first)' and the on-disk scope of counts. Still, it does not explicitly state that the operation is read-only with no side effects, nor how it behaves when no project is initialized beyond saying it shows whether one is.

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

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

The description is compact and front-loaded: the first sentence states the purpose, and the second adds the concrete contents without excess verbiage. Every sentence earns its place.

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

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

For a simple status-read tool with one documented optional parameter and an output schema present, the description covers the returned contents well. It is slightly incomplete in that it does not clarify read-only behavior or usage relative to sibling tools, but nothing needed to invoke it correctly is missing.

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

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

The single parameter 'lang' is fully described in the input schema, including its default and auto-detection behavior, so schema coverage is 100%. The description adds no parameter-level meaning, but none is needed because the schema already carries that burden.

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

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

The description uses a specific verb ('Return') and a specific resource ('status snapshot of the current project'), then enumerates exactly what the snapshot contains: initialization state, loaded roster, counts of open tasks/reports/issues, and recent activity. This clearly distinguishes it from the many list/detail sibling tools.

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

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

The intended use is implied: a concise overview of project state, as opposed to detailed per-item tools like list_tasks or list_reports. However, there is no explicit when-to-use or when-not-to-use guidance, nor any named alternative for digging into a specific aspect of the status.

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

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

With no annotations, the description carries the full burden, and it delivers: it enumerates every artifact written, the exact rule-file locations, the retained and removed v2 buckets, and the archival behavior under .fcop/migrations/<timestamp>/. It even explicitly notes that existing copies are archived so nothing is lost silently.

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 long and dense, but nearly every sentence carries concrete behavioral consequences; the core purpose is front-loaded. It could be tightened with bulleted structure and trimmed of internal references like §1.1, Rule 7.5, and ADR-0006, but overall it earns its length for a complex initialization 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?

Side effects and outputs are comprehensively covered, and an output schema exists, so return values do not need to be described. The main gap is the missing prerequisite that a project directory should be configured first (e.g., via set_project_dir), which would help an agent avoid calling this tool prematurely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats some force behavior already present in the schema but does not add meaningful new meaning about lang, team, or force beyond what the schema already documents.

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 first sentence states a specific verb and resource ('Initialize an FCoP project') and narrows scope to 'bundled preset team', which distinguishes it from siblings like init_solo and create_custom_team. The additional v2/v3 topology details further clarify exactly what kind of initialization this tool performs.

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 tool definition gives explicit routing guidance: solo mode should call init_solo instead, existing v2 projects should use migrate --to-v3, and force is appropriate when switching teams. This is explicit when/when-not guidance rather than leaving the agent to infer it.

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

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

With no annotations provided, the description carries the full behavioral burden and meets it. It discloses the v3 topology, that v2 buckets are no longer created, the exact deposited files, and that existing copies are archived under .fcop/migrations before being overwritten. This is unusually transparent for a mutating init tool.

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

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

The description is long but front-loaded with the core purpose and mode before the artifact list. The detail is earned by the tool's broad side effects, though a few clauses are slightly redundant (e.g., 'one AI, no dispatch' vs. 'single agent').

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 is complete about outputs and side effects, and an output schema exists so return-value details are not required. However, it does not state whether set_project_dir or a particular working directory is a prerequisite, which is a real gap for an initialization 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 100%, so the baseline is 3. The description does not add parameter-level detail beyond the schema; it mentions role_code and force only incidentally, not with new semantics.

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

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

The description states a specific verb and resource: 'Initialize an FCoP project in Solo mode.' It adds mode detail ('one AI, no dispatch') and lists concrete deliverables, which distinguishes it from generic team/init siblings without needing to inspect schemas.

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

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

It says solo mode is for projects where a single agent works directly with ADMIN, giving clear selection context. It does not explicitly name alternatives or say when not to use it, so it stops short of full when/when-not guidance.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the tool 'catches deterministic violations' and provides concrete examples, which signals a read-only validation behavior. It does not explicitly state 'does not modify the file', but the verbs 'validate' and 'inspect' strongly imply it.

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

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

The description is compact and front-loaded: the first sentence defines the action, and the second sentence adds concrete examples of what the tool catches. Every sentence earns its place with no filler.

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

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

For a tool with one well-documented parameter and an output schema, the description provides sufficient context about purpose and typical use. It could strengthen completeness by explicitly stating it is read-only or by naming related validation tools, but these are minor 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?

There is only one parameter and the schema already describes it thoroughly, including accepted forms ('Task filename or ID (same forms as read_task)'). Since schema coverage is 100%, the description does not need to add parameter details; it also does not add meaningful extra parameter semantics.

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

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

The description clearly states a specific action and resource: 'Validate a task file against FCoP grammar.' The examples make the tool's scope concrete. It does not explicitly distinguish itself from sibling validation tools like fcop_check, but it does separate itself from raw read_file + regex approaches.

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 clear context for when the tool is useful: when deterministic grammar violations need to be caught, especially ones that raw read_file + regex would miss. It does not explicitly say when not to use it or name sibling alternatives, but the use case is well 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?

No annotations are provided, so the description carries the full behavioral burden. It states 'Read' and refers to an 'append-only' log, which strongly implies a non-mutating, read-only operation with no side effects. However, it does not explicitly declare the absence of side effects, nor does it mention any authentication, rate limits, or error conditions. The description adds context (ADR-0030-bis Layer 1) and clarifies output content, but lacks explicit safety disclosures beyond the implication of 'read'.

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 concise—two sentences plus a bolded lead-in. It front-loads the core purpose ('FCoP governance audit') and then efficiently explains use and output. Every sentence earns its place with no redundancy or fluff.

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 tool has an output schema, so return-value details need not be repeated. The description fully explains what the tool does, why to use it, and what it returns (recent events with risk classification). All three parameters are optional and well-documented in the schema, so an agent has enough to call it correctly. Minor gaps like ordering or pagination semantics are covered by last_n and the output schema.

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

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

Schema description coverage is 100%, as each parameter (tag, risk, last_n) has its own detailed description. The tool description does not add further parameter semantics beyond what the schema already provides. Since the schema handles parameter meaning completely, a score of 3 is appropriate per the baseline for high coverage.

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

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

The description clearly states the tool reads an append-only governance event log and returns recent tool-call intercept events. It uses a specific verb ('Read') and resource ('governance event log'), and mentions the middleware and ADR reference, which distinguishes it from generic audit tools. However, it does not explicitly name sibling tools like fcop_audit or fcop_check, so differentiation is implicit rather than explicit.

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

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

It provides a clear context for use ('Use this to understand what actions agents have taken and their risk classification'), which tells an agent when to apply it. But it does not mention when not to use this tool or direct to any alternative sibling tools, so the agent must infer that other audit tools might serve different purposes without explicit 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 behavioral burden. It discloses the two distinct behaviors, states that all task entries under a date shard are listed, and gives the ordering of shards (newest first). The lack of detail about output shape is acceptable because an output schema is present, and 'List' strongly implies a read-only 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?

The description is two short sentences with no filler. It front-loads the core purpose, then immediately explains the two invocation modes in a compact, scannable way.

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

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

For a tool with one optional parameter, clear schema coverage, and an output schema, the description covers both call modes and the key ordering behavior. It does not specify the ordering of task entries within a date shard, but this is a minor omission given the tool's simplicity and the available schema/output schema.

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

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

The schema already documents the date format and the empty-string meaning, so the baseline is met. The description goes further by adding behavioral semantics: supplying a date yields every task entry under that shard, and omitting it returns shards newest first. This extra meaning helps the agent predict results more accurately.

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 a specific resource ('deep history archive'), and clearly describes the two modes: with a date it lists task entries under that date shard, without one it lists all date shards. It does not explicitly contrast itself with sibling tools like list_tasks or read_history_task, but the 'deep history' scope is distinguishable enough.

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

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

It clearly explains when to use the date parameter versus omit it, which directly guides invocation. However, it does not explicitly discuss tool selection relative to alternatives such as list_tasks or read_history_task; the 'deep history' framing implies the use case but leaves the comparison implicit.

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

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

With no annotations, the description carries the burden of disclosing behavior. 'List' weakly implies a read-only operation, but the description does not explicitly state side effects, permissions, or any behavioral nuances. It adds no behavioral detail beyond what the tool name already suggests.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple list operation, though it sacrifices behavioral detail that would have justified a higher score.

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

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

Given the presence of an output schema and full parameter documentation, the description covers the basic mechanics of listing and filtering. However, it omits usage guidance and behavioral transparency, and with zero annotations the overall context is thinner than ideal for an AI agent deciding when and how to invoke the tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description's mention of 'optionally filtered' adds no parameter-level meaning beyond the schema, but it also does not need to compensate for any coverage gaps. 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?

The description states 'List issues' with a clear verb and resource, and adds 'optionally filtered' to signal filtering behavior. It is not quite a 5 because it does not explicitly distinguish itself from sibling listing tools like list_tasks or list_reports, though the resource name makes the distinction reasonably obvious.

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

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

There is no guidance on when to use this tool versus alternatives, no exclusions, and no context about when filtering or pagination would be appropriate. The name implies its use case, but the description itself provides no explicit usage direction.

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 only says 'optionally filtered' without disclosing defaults, return format, pagination behavior, or that it returns a list of report objects. The schema provides defaults, but the description adds no behavioral context beyond that.

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 efficient sentence with no waste. It is appropriately sized for a list operation, though it could be slightly more informative without being verbose.

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

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

Given no annotations and an output schema that may explain returns, the description still fails to disclose core behavioral traits like default filtering (status='open') or that pagination is available via limit/offset. An agent cannot infer when to use this vs other tools or what side effects might occur.

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%, with each parameter already documented. The description adds no additional meaning beyond 'optionally filtered', which is implied by the optional parameters. Baseline of 3 applies since the schema does the heavy lifting.

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

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

The description states a clear verb and resource ('List reports') and mentions optional filtering. However, it doesn't differentiate from sibling tools like list_tasks or list_history; the name itself is unambiguous enough.

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

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

No guidance on when to use this tool vs alternatives. There is no mention of context like 'use this to fetch report summaries' or 'prefer read_report for a single report'. The description simply restates the obvious.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only listing operation but does not mention pagination behavior, return size limits, the default 'open' status filter, or any other significant behavior, leaving nearly all behavioral detail to the schema.

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

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

The description is a single front-loaded sentence with zero filler, immediately stating the verb and resource. It is appropriately brief for a simple list tool, though its brevity leaves usage and behavioral guidance unaddressed, which is a completeness issue rather than a conciseness issue.

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 output schema and fully documented input schema cover the calling contract effectively. What is missing is usage guidance among a large sibling set, behavioral expectations, and clarification of the 'REVIEW files' concept, making the description minimally complete but not self-sufficient for agents.

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%, with defaults and allowed values already documented for all six parameters. The description adds only a generic 'optionally filtered' summary, which does not explain any parameter meaning beyond what the schema provides, matching the high-coverage baseline of 3.

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

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

The description states a clear verb and resource ('List REVIEW files') and a specific capability ('optionally filtered') that maps to the six optional filter parameters. It is not a tautology of the title, though it does not explain what a REVIEW file is or explicitly differentiate itself from siblings like list_reports and list_tasks.

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

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

No guidance is offered about when to use this tool rather than read_review, list_reports, or list_tasks. The phrase 'optionally filtered' hints at filter-driven use cases but provides no exclusions, prerequisites, or conditions for choosing this tool over alternatives.

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

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

With no annotations, the description must carry behavioral disclosure, and 'List' does convey a read-only, non-destructive operation. However, it does not mention the default status of 'open', pagination behavior, or any details about which task states are included, leaving the agent to infer those traits from the schema.

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

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

The description is one short sentence with the action and resource front-loaded, and 'optionally filtered' is the only qualifier. No words are wasted, making it exemplary in 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?

An output schema exists and the input schema is fully described, so the description does not need to explain parameters or return values. However, for a tool with many sibling list variants and no annotations, the one-line description leaves selection context and behavioral defaults to be inferred, so it is minimally adequate but not complete.

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

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

Schema description coverage is 100%, with all six optional parameters documented including defaults and matching rules. The description adds no parameter-level detail, so it neither helps nor hurts beyond the schema, matching the baseline of 3.

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

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

The description names a specific verb and resource, 'List tasks', and adds the useful qualifier 'optionally filtered'. It is clear about the core operation, but it does not distinguish this from sibling list tools nor from read_task or inspect_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?

No guidance is given on when to use this tool versus alternatives such as list_history, list_reports, or read_task. The phrase 'optionally filtered' implies some filtering use cases, but there are no explicit conditions, exclusions, or alternative routing.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that hand-created directories appear with only the slug and marker-created workspaces include metadata. However, it does not describe the actual metadata contents, sorting, or potential side effects, though as a read-style list the core behavior is adequately conveyed.

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

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

The description is compact and front-loaded, with the primary action in the first sentence. The following sentences add genuinely useful distinctions about directory discovery and display without 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?

Given a simple one-parameter schema, an output schema, and no nested objects, the description covers the important operational details: what is listed, how hand-created directories are treated, and when to use the tool. No critical information needed to call it correctly is missing.

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

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

The schema already documents the single optional lang parameter with 100% coverage, so the baseline is 3. The description adds no parameter-specific detail, but none is needed because the schema fully explains the parameter.

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

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

States a specific verb and resource: lists workspace/<slug>/ subdirectories with metadata. It also distinguishes the tool from new_workspace by explaining it discovers both marker-created and hand-created directories, leaving no ambiguity about its scope.

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

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

Provides a clear use case: "at-a-glance what's inside this project" view. It does not explicitly name alternatives or exclusion conditions, but the usage intent is unambiguous and distinct from sibling tools.

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

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

With no annotations, the description carries the behavioral disclosure. It discloses the write effect on the REVIEW frontmatter and mentions the returned update. However, it does not state permissions, state prerequisites beyond 'needs_human', or behavior on reject vs approve.

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 scoped sentences: first states the action and target, second explains lifecycle context and the returned result. No filler; front-loaded with purpose.

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 explains when this tool fits in the workflow (closing the write_review escalation loop) and what it returns. It omits some stateful details like whether the review must currently be in needs_human status, but the output schema exists and the reference to ADR-0026 provides context.

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

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

Schema covers 100% of parameters with descriptions, so baseline 3 applies. The description adds no extra parameter meaning beyond the schema, but none is needed.

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

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

The description uses a specific verb ('Record') and resource ('needs_human REVIEW file'), and explicitly distinguishes itself by naming the escalation loop opened by write_review(decision='needs_human'), separating it from sibling tools like write_review and approve_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?

It clearly states the trigger: a review needs human approval after write_review(decision='needs_human'). It does not explicitly list alternatives or exclusions, but the lifecycle reference gives enough context for an agent to know when to invoke it.

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

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

No annotations are provided, so the description carries the full behavioral transparency burden. It does this well by explicitly disclosing idempotency: calling twice with the same slug updates title/description but never deletes files already present in the folder. It does not claim the second call creates a duplicate or destructive state, which is the most important behavioral trait here.

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

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

The description is short and front-loaded: it gives the immediate action first, then explains the purpose of the workspace convention, then states the key safety behavior. Every sentence earns its place and there is no filler or redundant restatement of the schema.

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 three-parameter tool with 100% schema coverage and an output schema, the description provides adequate context: exact resource, purpose, folder location, and behavioral guarantee. It could be slightly more explicit about how this tool relates to siblings like init_project or set_project_dir, but that is a minor gap, not a usability blocker.

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

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

Schema coverage is already complete (100%), but the description adds meaningful parameter semantics beyond the schema. It clarifies that `slug` is the stable workspace key, and that reusing the same slug causes an update of title/description rather than failure or recreation. This is useful behavior for an agent deciding how to call the tool on an existing workspace.

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

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

The description opens with a precise action and resource: 'Create a workspace subdirectory under workspace/<slug>/.' This clearly identifies the tool's function and the path it operates on. It does not explicitly name sibling tools, but the verb and path make the purpose far more specific than the generic title 'New Workspace.'

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 clearly communicates the intended use context: workspace directories are FCoP's convention for actual work artifacts, and using them avoids colliding with unrelated project files. It implies when the tool should be used, though it does not explicitly mention when _not_ to use it or name an alternative sibling tool.

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

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

With no annotations provided, the description carries the full burden. It explains the search behavior (in history/ directory, date shard optimization) but doesn't disclose return format, error handling, or whether it's read-only. It's a read operation by implication, but not explicitly stated. There's no contradiction, but it's sparse.

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 paragraphs with key information front-loaded. No fluff. The example format for task_id is helpful. It's concise and well-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?

Given the tool has an output schemahandled, the main gaps are lack of when-to-use guidance and minimal behavioral transparency (since no annotations). The description is sufficient for basic invocation but lacks depth for an AI agent to be fully confident about side effects and edge cases.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the meaning of date as a restriction for speed, which is useful, and mentions task_id can be a full filename, which is beyond the schema. However, it's not extensive.

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

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

The description clearly states it reads a task from the deep history archive by task_id, which is specific and distinguishes it from siblings like read_task (which likely reads current tasks). It could be more explicit, but the verb-resource pair 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?

The description implies usage for archived tasks and mentions that providing date restricts the search to a date shard for speed, but it doesn't explicitly contrast with read_task or other alternatives. No 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 supplied, the description carries the full burden. It indicates a read-only operation via the verb 'Read', but says nothing about failure modes (missing file), permissions, or that no changes will be made. This is minimal behavioral disclosure for a tool with no annotation support.

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, tightly composed sentence with no filler or repetition. It is appropriately short for such a simple tool, though 'report file' is slightly vague compared to the schema's clarification.

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 tool with an output schema, the description covers the core operation, but it misses relational context: it doesn't clarify when to use this instead of list_reports, read_task, or read_review, nor does it address any specifics about the output. The provided output schema compensates for return information, but the contextual ambiguity remains.

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

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

Since the schema description provides complete coverage of the 'filename' parameter (allowing a filename or task_id), the description adds little extra beyond the word 'report'. Baseline is therefore a 3 because the schema already explains the parameter fully.

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

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

The description clearly states the verb 'Read' and the resource 'report file', and adds 'full content', which distinguishes it from listing or writing reports. However, it doesn't explicitly differentiate from sibling read tools like read_task or read_review by mentioning the resource type beyond 'report file'.

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

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

The intended usage is implied: use when you need the full information from a report. But the description provides no explicit guidance about when not to use it (e.g., when you only need metadata or to list reports) or comparisons to alternatives like list_reports or read_review.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Read the full content' without mentioning whether the file must exist, what happens if the filename is invalid, whether it returns raw markdown or parsed content, or any side effects. For a read operation this is a moderate gap, but the lack of any behavioral detail beyond the verb leaves the agent guessing about error behavior and return format.

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 sentence with no waste. It front-loads the action and resource. However, it could have added a brief note about the return format or error behavior without becoming verbose.

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 tool has a single parameter, an output schema, and a clear read-only purpose, so the description is mostly adequate. However, with no annotations and no mention of what the output contains or how to handle missing files, an agent might not know what to expect when invoking it. The output schema likely covers return values, but the description doesn't reference it.

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

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

Schema description coverage is 100%, so the schema already documents the filename parameter with a format hint. The description adds no additional meaning beyond what the schema provides, 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?

The description states a specific verb ('Read') and resource ('REVIEW file'), which clearly identifies the tool's function. It doesn't explicitly differentiate from sibling tools like read_report or read_task, but the resource type is distinct enough that an agent can infer the difference.

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 usage context: use this tool when you need the full content of a review file. It doesn't explicitly state when not to use it or name alternatives like list_reviews for browsing reviews, but the context is reasonably clear given the sibling set.

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 states the operation is reading, which implies non-destructive behavior. The input schema reveals that both open and archived tasks are searched, but the description doesn't disclose that, nor does it mention any side effects or prerequisites. Reading a file is inherently safe, but the description could state that it doesn't modify anything. It's adequate but minimal.

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, concise sentence that directly states the action and object. It is front-loaded with the main purpose and has no fluff. It 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 read operation with one parameter and an output schema present, the description is sufficient. The schema provides parameter details, and the output schema defines return values. However, the description doesn't mention that both open and archived tasks are searched, which is a key behavioral detail. Since the schema covers that, it's not a critical gap, but it would be helpful context for an agent to know without opening 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 coverage is 100%, so the schema already documents the 'filename' parameter, including examples and the fact that both open and archived tasks are searched. The description does not add additional information about the parameter beyond what the schema provides. Per calibration, when schema coverage is high, baseline is 3, and the description offers no extra value.

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

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

The description clearly states the verb 'read' and the resource 'task file', and explains it reads the full content. It distinguishes from siblings like inspect_task and list_tasks, though it doesn't explicitly name them. The use of 'full content' suggests it's the complete read operation, which adds specificity.

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 usage: when you need the full content of a task filecars. However, it doesn't explicitly contrast with sibling tools like inspect_task or list_tasks, which might provide summaries or metadata. Since the tool name and title already convey 'read' vs 'list' or 'inspect', the usage context is implied but not explicit. No exclusions or alternatives 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?

With no annotations provided, the description carries the full transparency burden. It discloses that the tool writes files, overwrites existing content when force is true, archives previous versions when archiving is enabled, and can behave destructively when archiving is disabled. It also flags the ADMIN-only authorization requirement.

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 organized into a clear summary, a file-location list, a usage trigger, and an access restriction. It is slightly verbose but every sentence adds operational context that is not present in the schema.

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

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

Given that no annotations are provided, the description carries the full burden. It covers purpose, destination files, upgrade timing, drift detection, destructive behavior, and the ADMIN-only restriction, which makes the tool's context sufficiently complete.

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

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

Schema coverage is high since both parameters already have detailed descriptions explaining defaults and behavior. The tool description does not add much meaning to the parameters beyond context for when the operation is appropriate, which is more about usage than parameter semantics.

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

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

The description immediately identifies the action as re-deploying bundled FCoP protocol rules to specific project files. It names the resource ('bundled FCoP protocol rules'), the destination file set, and the tool's role in refreshing on-disk copies. This leaves little ambiguity about what the tool does.

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

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

The description explicitly states when to run the tool: after `pip install -U fcop-mcp` or `fcop`, and mentions that `fcop_report()` signals when it is needed via version drift. It also gives a hard restriction that only ADMIN may invoke it, per ADR-0006, which is essential usage guidance.

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

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

With no annotations, the description carries full responsibility and does well: it discloses the file move across lifecycle directories, the appended `reject_task` transition event, the non-destructive nature, and the v2 no-op behavior. It does not mention permission prerequisites or failure behavior, but the core side effects are clearly surfaced.

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

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

The description is front-loaded with the core state transition and stays compact. There is minor redundancy between the first and second sentences, but every behavioral point 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?

Given an output schema exists, return-value documentation is unnecessary. The description covers lifecycle semantics, exact file paths, event logging, non-destructive intent, and version compatibility, leaving only minor gaps around error cases and permission enforcement.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds little param-specific meaning. It implies the ADMIN actor role by describing the ADMIN recall mechanism, but the individual parameters `task_id`, `actor`, and `note` are left to the schema.

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

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

States a precise verb pair (reject/recall), the exact target resource (task under review), and the state transition `review → active`. The file-path move and v3 lifecycle context make it clearly distinct from siblings like approve_task, archive_task, or submit_task.

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

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

Gives clear usage context: ADMIN sends work back for revision without discarding it, and the task returns to active for rework. Also provides an explicit exclusion by noting it is a no-op on v2 projects, though it does not name alternative tools or conditionally compare them.

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

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

With no annotations, the description carries the full burden of revealing side effects. It explicitly states that the tool writes nothing, is safe to call while UNBOUND, is not a role-claim, only mutates in-process state, and affects every subsequent tool call but not mcp.json or the running Cursor process.

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

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

The description is front-loaded with the single-sentence purpose and each subsequent sentence adds distinct value: when to use it, what it changes, and what it does not do. It is compact with no filler or repeated material.

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, session-scoped configuration tool with an output schema, the definition covers the required scenario, the operational effect, the safety profile, and the parameter constraints. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and the path parameter is already well-documented in the schema, including absolute path, expected contents, and existence requirement. The tool description reinforces that the path is the project root used for re-binding, but adds no new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Pin the project root for this MCP session.' It goes on to say the tool re-binds every subsequent tool call to the given directory without editing mcp.json or restarting Cursor, which clearly separates it from configuration and project-lifecycle siblings like init_project or new_workspace.

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 a concrete when-to-use context: when the MCP process was spawned with the wrong working directory, and identifies the typical symptom via unbound_report showing a user path instead of the Cursor workspace. It does not name alternative tools, but the described use case is specific enough that an agent can decide when this tool is appropriate.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the filesystem move, the appended transition event, and the v2 no-op behavior. An agent can predict concrete side effects before calling the tool.

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

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

Three sentences, no filler, and the essential state transition is front-loaded. The no-op warning is included without expanding the description unnecessarily.

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

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

For a state-transition tool with full schema coverage and an output schema, the description provides everything needed to invoke it correctly: the transition, the file location, the event append, and the v2 exception.

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?

Input schema coverage is 100%, so both parameters are already documented. The description adds lifecycle context but no additional parameter-level detail beyond the schema, which fits the baseline 3 for high schema coverage.

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

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

States a specific verb and resource, 'Submit an active task for review', and defines an exact state transition: active → review. This clearly differentiates it from sibling lifecycle tools like finish_task, approve_task, and reject_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 description clearly indicates the tool is for moving an active task into review, which is the context of use. The explicit 'On v2 projects this is a no-op' caveat gives important conditional guidance, though no sibling tool is named as an alternative.

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

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

With no annotations, the description carries the full burden. It clearly states that the tool does NOT run pip and explains why, and that it prints a command for the user to run. This is transparent about its non-mutating behavior. It doesn't describe edge cases (e.g., unsupported install methods) but covers the main points.

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

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

The description is two sentences, front-loaded with the core purpose, and includes necessary context (why it doesn't run pip) without fluff. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and an output schema, the description is complete. It explains what it does, why, and what it doesn't do. It doesn't detail the exact output format, but that's covered by the output schema. The description gives enough context for an agent to know when and how to call it.

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

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

The single parameter 'lang' is fully described in the schema ('Output language, zh or en.'), and the tool description adds no additional context about it. Schema coverage is 100%, so a baseline of 3 is appropriate; the description doesn't enhance understanding of the parameter beyond the schema.

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

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

The description states a specific verb ('Return') and resource ('install-method-specific command to upgrade fcop-mcp'), clearly distinguishing it from any sibling tool. The purpose is unambiguous and concrete.

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

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

The description explains when this tool is needed (to get the correct upgrade command) and explicitly states why it doesn't run pip directly, providing reasoning. However, it doesn't explicitly mention alternatives or exclusions beyond that, so it's slightly below a perfect score.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so well: it states the operation is a dry run and explicitly says it writes nothing to disk. It also enumerates the validation checks performed, which helps the agent understand what the tool will and won't catch.

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 compact and front-loaded: it leads with the core purpose, then the usage context, then the side-effect guarantee. Every sentence earns its place with no redundant wording.

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 tool with full schema documentation and an output schema, the description is complete. It covers purpose, usage timing, side effects, and validation scope, so an agent has enough to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying what makes role codes illegal (Chinese characters, dashes, reserved names, duplicates), which informs valid values for the roles and leader parameters.

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

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

The description states a specific verb ('dry-run validation') and a specific resource ('custom team config'), and immediately distinguishes itself from the sibling create_custom_team by noting it catches illegal role codes without writing to disk. An agent can tell exactly what this tool does and what it is not.

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 explicitly says to use this tool 'before create_custom_team' and names the concrete failure classes it catches (Chinese characters, dashes, reserved names, duplicates). This gives clear when-to-use guidance relative to the most relevant sibling tool.

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

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

There are no annotations, and the description only says an issue is filed in a directory. It does not disclose file creation behavior, naming conventions, overwrite risk, or what happens on execution.

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 concise, front-loaded sentence with no filler or restatement of the tool name.

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

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

For a file-creating mutation tool, the description omits critical context: filename derivation, overwrite behavior, required parent directories, and return/confirmation behavior.

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

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

Schema coverage is 100%, so parameters are already well described. The description adds little beyond operational context, which meets but does not exceed the baseline.

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 clear action ('File an issue') with a specific target location ('docs/agents/issues/'). It distinguishes this from sibling write tools such as write_report and write_review.

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

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

No guidance is given about when to choose write_issue versus other tools, nor about prerequisites such as existing directory structure or whether the issue must be approved before creation.

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 full responsibility for behavioral disclosure. It states the file it creates and its location, but does not mention whether it overwrites existing files, any permission requirements, side effects on task state, or error behavior. For a tool that writes to disk, 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?

The description is two sentences with no filler. It front-loads the purpose and immediately provides the concrete file naming and location, then clarifies the role of task_id. 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?

The description covers the core behavior (file creation, naming, path) but does not mention when to use this tool versus siblings like write_issue or write_review, nor any prerequisites or side effects. Since an output schema exists, the return value is covered elsewhere, but the lack of usage context and alternative differentiation leaves the agent under-informed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that task_id, reporter, and recipient are used in the generated filename, which the schema does not convey. It also clarifies task_id as the canonical reference, enriching the meaning beyond the schema's simple 'Source task ID'.

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

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

The description clearly states the verb 'write' and the resource 'completion report for a task', and gives the specific file naming convention and path. It is specific enough to distinguish from generic report writing, but it does not explicitly differentiate from sibling tools like write_issue or write_review, so it misses the highest level of clarity.

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 usage for completion reports ('Write a completion report for a task') and gives the file path, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., write_issue, write_review). No exclusions or conditions are stated, leaving the agent to infer.

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

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It only states the action without mentioning side effects (e.g., file creation/overwrite), required capabilities (like review_decision, which is in the schema but not the description), output behavior, or escalation flow. This is a serious gap for a tool with complex governance semantics.

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

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

The description is a single sentence with no fluff, and the core purpose is front-loaded. However, it is so terse that it sacrifices helpful context for brevity, though it remains appropriately concise given the rich schema.

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 9 parameters, an output schema, and no annotations, the description is too sparse. It does not explain the review workflow, the significance of decision types, the requirement for required_changes with needs_changes, or the human escalation mechanism (needs_human / mark_human_approved). An agent relying solely on the description would lack critical operational context.

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

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

Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description adds nothing about parameters, but per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action (Write) and the resource (a REVIEW file) with a specific governance-layer decision context. It distinguishes this from sibling read/list tools like list_reviews or read_review, and the verb is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The phrase 'governance-layer decision' hints at context but does not specify when a review should be written, when to use mark_human_approved instead, or any conditions.

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 behavioral disclosure burden, and it does disclose file creation, filename generation, frontmatter/body writing, and v2/v3 placement. It does not cover overwriting behavior, required project setup, permissions, or failure modes, but the core side-effect is visible.

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 efficient, front-loaded with the primary action, and each sentence contributes useful context: path, filename, and downstream claim workflow. There is no filler, though the v3/v2 path details could potentially be more compact.

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

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

The description covers the important context for a creation tool: what file is written, where it is placed, the filename shape, and the downstream claim step. Given the full input schema, an output schema, and no annotations, this is largely complete, though the relationship to create_task remains a gap.

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

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

Input schema coverage is 100%, so every parameter is fully documented in the schema itself. The description adds little beyond stating the generated filename uses sender and recipient, which is enough to meet the baseline but no more.

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

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

The description clearly states that the tool creates a new task file and gives concrete details about paths and filename format. However, it does not differentiate write_task from the closely named sibling create_task, so it is clear but lacks sibling discrimination.

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 usage context by explaining where the task file is placed and that the recipient can claim it. It does not explicitly state when to use this tool over create_task or other task lifecycle tools, nor does it give exclusions, so guidance remains implicit rather than direct.

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