fcop-mcp

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

With no annotations, the description fully discloses behavior: moves task file from _lifecycle/review/ to _lifecycle/done/, appends an approve_task event, and is a no-op on v2 projects. This gives a complete picture of side effects and constraints.

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?

Four sentences, front-loaded with the main action. Every sentence is meaningful and without fluff. Highly 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 moderate complexity (state transition, file move, event logging) and the presence of an output schema, the description covers lifecycle details, file movement, event appending, v2 no-op, and role requirements. No gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra context, e.g., 'Optional approval note appended to the transition event' for the note parameter. 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?

Clearly states 'Approve a task under review: review → done (v3 lifecycle)', specifying the verb, resource, and state transition. Distinguishes from siblings like reject_task and 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?

Indicates 'Typically called by ADMIN after inspecting the work', providing clear usage context. Also notes 'On v2 projects this is a no-op', effectively excluding certain scenarios. Lacks explicit naming of alternative 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 provides moderate behavioral insight: it moves the task under a log directory and also moves any associated report. However, it does not mention prerequisites, reversibility, or side effects, leaving gaps for the agent.

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, each adding value. The first sentence gives the primary action with a concrete path; the second covers the report handling. 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?

Given the tool's simplicity and the presence of an output schema, the description covers the core behavior (archiving task and report). Minor gaps exist (error states, permissions), but it is largely complete for an archive operation.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds no extra meaning beyond what is already in 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?

The description clearly states the verb 'archive', the resource 'completed task', and the specific destination 'docs/agents/log/'. It also adds the nuance about moving the report file, which distinguishes it from siblings 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 description implies the task should be completed but does not explicitly state when to use this tool versus alternatives like archive_to_history or bulk_archive_to_history. No exclusion criteria or alternative tool mentions are provided.

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

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

Discloses that both task and reports are moved, creates immutable date-sharded record, and documents date default behavior with override option. No annotations provided, so description carries full burden; it does well.

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?

Well-structured into two paragraphs: action overview then prerequisite/details. Every sentence is informative. Could be slightly more concise but overall efficient.

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

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

Covers purpose, parameters, prerequisite, and output format hints (date-sharded path). Has output schema so return values not needed. Adequate for an agent to use 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 already describes both parameters (100% coverage). Description adds format examples for task_id and explains default behavior for done_date. Adds value beyond 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?

Clearly states the action: move a closed task from `_lifecycle/archive/` to deep history archive. Specifies source and destination directories and that all associated reports are moved together, distinguishing it from siblings like 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?

Explicitly states prerequisite to call archive_task first. Implicitly differentiates from bulk_archive_to_history (single task vs bulk). Does not explicitly list when not to use, but context is clear.

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

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

With no annotations, the description fully discloses the behavior: iterating over every task, calling archive_to_history, moving tasks with reports, and auto-creating the history directory. This makes the operation transparent. It doesn't cover permissions or error handling, but the core behavior is well explained.

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 moderately sized but each section adds value: purpose, operation detail, use cases. It is front-loaded with the bold main action. Some minor redundancy (e.g., 'iterates every task... and calls archive_to_history for each one') is fine. It earns its length.

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

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

Given the tool has only one optional parameter, an output schema (existence known but content provided by signals), and no annotations, the description covers the essential aspects: what it does, how it works, when to use, and the parameter. It is complete enough for an agent to use 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% (the one parameter done_date is described in the schema). The description adds no extra information beyond restating the schema's purpose. Per guidelines, with high coverage, baseline is 3, and the description does not exceed that.

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 specifies the exact action: migrating all tasks from _lifecycle/archive/ to history/ with date sharding. It distinguishes itself from the sibling tool archive_to_history by being a bulk operation, and the verb 'migrate' combined with the source/destination makes the purpose crystal 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 provides explicit 'Useful when' scenarios (project upgrade or after manual archiving) that help the agent decide when to invoke this tool. It implicitly contrasts with the per-task archive_to_history. No explicit 'when not to use' but the scenarios are clear enough for a specialized migration tool.

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

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

No annotations provided, so description carries full burden. It discloses that the tool prints version info and does not install, with a recommendation for upgrade. Transparent about its behavior.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

Given the simple single parameter, existing output schema (context signals), and clear description of return values (local version, latest version, verdict), the tool 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?

Schema coverage is 100%, and the description does not add extra meaning beyond the schema's 'lang' parameter description. 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 tool compares installed fcop-mcp version to latest on PyPI, prints details, and explicitly distinguishes from upgrade_fcop by noting it does not install. Verb+resource is specific.

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: use to check version, then call upgrade_fcop to upgrade. It names the alternative tool but does not explicitly state when not to use it, though 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 provided, so description carries full burden. It details the file move and frontmatter append, and notes v2 behavior. While it doesn't mention permissions or idempotency, it is fairly transparent about core actions.

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

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

Three sentences, front-loaded with purpose, followed by mechanics and an edge case. No wasted words, efficient and clear.

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 simple operation and full schema coverage with output schema present, the description covers the transition, file movement, and v2 exception. No major gaps for an agent to invoke 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 baseline 3. Description does not add significant meaning beyond schema descriptions; it contextualizes the operation but not the parameters themselves.

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 claims a task moving it from inbox to active, referencing the v3 lifecycle. It mentions v2 no-op, which adds specificity. However, it does not explicitly differentiate from sibling tools like approve_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 description implies use when wanting to claim a task, but provides no guidance on when not to use it or alternatives. No comparison with 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 full burden. It discloses the force mode's archival behavior, the v3 topology change, and that custom teams leave shared/ empty. It lacks mention of auth or rate limits, but these are less critical.

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 purpose, then organized into logical sections: role codes, topology, custom team specifics, force behavior. It is slightly verbose with spec references but remains focused 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?

Despite having an output schema (not shown), the description covers all essential aspects: purpose, parameters, side effects, post-creation steps, and sibling tool reference. It is highly complete for a tool with 5 parameters and complex 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%, baseline 3. The description adds value by explaining role codes become part of filenames, leader must be in roles, force archives files, and lang defaults to zh. This enriches the bare parameter descriptions.

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

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

The description opens with 'Create an FCoP project with a custom roster of roles,' which clearly states the action and resource. It distinguishes itself from siblings like validate_team_config (pre-check) and init_project/init_solo (preset-based) by focusing on custom role rosters.

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 advises using validate_team_config first to catch invalid role codes. It implies when to use this tool (custom teams) vs presets by noting that custom teams lack bundled docs, but does not give an explicit when-not-to-use list.

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

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

With no annotations, the description carries the full burden. It discloses the routing behavior (task placement in inbox/tasks folder) and the ability for the recipient to claim the task. However, it does not cover side effects, permissions needed, idempotency, or error states, leaving some behavioral gaps.

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

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

The description is extremely concise: three sentences with no redundant words. The first sentence conveys the core action, the second provides spec context and relation to sibling, and the third gives routing details. 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?

Given the tool's complexity (8 parameters, 4 required, full schema, output schema present), the description provides sufficient high-level context: the canonical spec role and routing behavior. It does not explain parameters (already in schema) or return values (output schema exists). It could be more complete by mentioning prerequisite checks or error conditions, but for a creation tool this is adequate.

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 no additional meaning to the parameters beyond what the input schema already provides. The parameters are fully documented in the schema, so the description does not need to compensate.

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 creates a new task and places it in a specific location (inbox for v3, tasks folder for v2). It distinguishes itself from the sibling write_task by noting it is the canonical FCoP v3 spec entry-point, though functionally identical.

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 context on when to use the tool (as the spec-defined entry-point) and mentions the alternative write_task. It explains where the task lands (inbox for v3, tasks folder for v2) and that the recipient can claim it, but does not explicitly list when not to use it.

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

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

No annotations provided, so the description fully carries the burden. It comprehensively discloses: file writing, archiving under .fcop/migrations, reversibility, and bilingual variants. All relevant behavioral traits are covered.

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

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

The description is concise (4 sentences), front-loaded with the primary action, and structured logically: first the overall function, then file listing, then force behavior. No extraneous 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?

Given 3 parameters, no output schema required, and clear handling of force vs skip, the description covers the tool's operation well. Minor omission: it doesn't mention whether the tool requires initialization, but that is implicit from the 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 coverage is 100% with good descriptions. The description adds value by clarifying default behavior (empty uses fcop.json) and the archiving mechanism for force. This goes beyond the schema's basic parameter descriptions.

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

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

The description explicitly states 'Deploy the three-layer team documentation' and lists specific files (TEAM-README.md, TEAM-ROLES.md, etc.), providing a clear verb+resource. No sibling tool performs a similar deployment, so distinction is inherent.

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

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

The description explains the force parameter behavior (archive vs skip) and notes defaults from fcop.json. While it doesn't explicitly state when to use this tool vs alternatives, the context is clear enough given no similar siblings.

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

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

No annotations, so description carries full burden. It discloses file creation under .fcop/proposals/, timestamped, for ADMIN review, and that it works before init. Minor omission: doesn't specify whether it overwrites existing proposals, but timestamping implies unique files.

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

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

Four sentences, each adding distinct value: purpose, mechanism, usage rule, extra context. No fluff, well-organized.

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 (2 params, 1 required, output schema exists), the description covers purpose, usage, behavior, and edge cases completely. No gaps.

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

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

Schema coverage is 100% and schema descriptions are already clear. The description adds minor context (rendered as separate block) but mostly paraphrases 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 clearly states the tool's purpose: a 'pressure valve' for agents to disagree with FCoP protocol by writing a timestamped markdown file. It distinguishes itself from siblings by being the only sanctioned way to push back on rule files.

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

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

Explicitly says when to use (disagreement with protocol) and when not (MUST NOT edit rule files). Also notes it works before project initialization, providing clear context.

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

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

No annotations provided, so description carries full burden. It details output format (file path), includes Execution Block with remediation commands, priorities, and rollback instructions, and explains delivery modes.

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

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

Well-structured with clear sections, comparison, and bullet points. Every sentence adds value, though slightly verbose with markdown formatting.

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, the description is highly complete, covering purpose, usage, output, parameters, and sibling differentiation. No missing critical information.

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 provides 100% coverage for 3 parameters with descriptions. The description adds context by explaining scope values and output options, but schema already does most of the work.

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 is a protocol compliance audit tool that scans projects, identifies compliance gaps, and produces a report. It uses specific verb+resource and distinguishes from sibling fcop_check.

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 compares with fcop_check, providing when to use each tool. Lists four scopes (new, upgrade, takeover, auto) with descriptions, guiding appropriate usage.

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 fully discloses behavioral traits: it decomposes to filesystem operations (git status, walking files, reading frontmatter only), and declares it is detection, not prevention. This provides sufficient transparency beyond the absence of annotations.

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

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

The description is well-structured with bullet points and clear sections, explaining the two audits concisely. It is verbose enough to be informative but not overly long, earning a high 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 output schema exists, the description does not need to explain return values. It covers prerequisites (project root implied) and operational details (filesystem ops). It provides enough context for an AI agent to understand scope and usage.

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 one optional parameter 'lang' described in the schema. The tool description does not add meaning beyond the schema's parameter description. Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: cross-referencing git working tree and frontmatter against the FCoP ledger, with two specific audits (Rule 0.a.1 drift and Rule 1 sub-agent role impersonation). The verb 'audit' and resource 'FCoP ledger' are specific, and the tool is distinguished from siblings like fcop_report and fcop_audit.

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 states usage as detection not prevention, and that the response is for ADMIN to file an ISSUE-*. This provides clear when-to-use and when-not-to-use guidance. It does not explicitly compare to sibling tools like fcop_report, but the context is implied via sibling names.

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

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

With no annotations provided, the description carries the full burden. It discloses the output format ('Creates a new ALERT-*.md file in fcop/alerts/'), the required role (ADMIN/Governance Observer), and implies a non-destructive write operation. Adding details about persistence or side effects would raise the score further.

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 extremely concise—two sentences plus a preliminary role note. It front-loades critical authorization info, uses bold for emphasis, and every sentence adds value. No 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 the tool has an output schema (not elaborated in description, but per rules not required) and the description covers purpose, usage context, and output format, it is fully complete for an agent to understand and invoke 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?

The input schema has 100% description coverage for all four parameters. The description does not add new meaning beyond what the schema already provides (e.g., severity values, alert_type enum, summary format). Therefore, per calibration, 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 clearly states the tool's action ('manually file a governance alert') and the resource ('governance alert'). It distinguishes from sibling tools by specifying that it is for gaps not captured by automated scanning, making its purpose unique and specific.

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 indicates when to use the tool ('when you detect a governance gap that automated scanning has not yet captured') and the required role (ADMIN or Governance Observer). It does not provide explicit alternatives or when-not-to-use scenarios, but the context is clear enough for a well-informed 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 describes that alerts are created automatically by fcop_check(), the file format (ALERT-*.md), and severity levels. It does not mention authentication needs or rate limits, but as a read-only list tool, this is acceptable.

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 paragraphs that front-load the purpose and then add context. Every sentence adds value, with no wasted words. Could be slightly more streamlined but 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?

Given the presence of an output schema and the simplicity of the tool (list with optional filters), the description is complete. It explains the source, structure, and use case, and the schema covers parameters thoroughly.

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%, and each parameter has a clear description. The description adds little beyond the schema, noting that filters are available but not providing extra semantics. Baseline of 3 is appropriate.

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

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

The description clearly states it lists governance alerts from fcop/alerts/, explaining the structure and purpose. It distinguishes itself from sibling tools like fcop_check and fcop_create_alert by positioning itself as the admin's 'red dot' for surfacing gaps, making the purpose very specific.

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 tells when to use it (to see governance gaps without manual log patrols) and implies admin use. However, it does not explicitly mention when not to use it or compare with alternatives like fcop_audit or fcop_check, leaving some ambiguity.

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 fully discloses behavioral traits: it detects initialization state, returns appropriate reports, includes versions block, and appends drift warning. It also notes that agents must not invoke redeploy. However, it does not explicitly state whether the tool is read-only (but heavily implies 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 well-structured with bullet points and a note, but slightly verbose. Every sentence adds value, but the deprecation note could be integrated more concisely. Still, it maintains clarity.

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 comprehensive: covers two report types, versions block, drift warning, behavioral constraints, and deprecation history. With an output schema present, return values are documented externally, making this 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% with one parameter 'lang' having a clear default and description. The description adds no further semantic meaning beyond what the schema already provides, so 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 it is the 'first tool call of every new session' and a 'general project-status report', specifying it returns one of two reports (initialization or UNBOUND) plus a versions block and optional drift warning. It explicitly distinguishes from siblings by noting it replaced 'unbound_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 explicitly says it must be the first tool call of every new session. It also provides clear constraints: while UNBOUND, the agent must not read task bodies, write files, or claim a role. It warns against invoking 'redeploy_rules' directly. This is comprehensive 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 covers the core behavioral traits: moving a file between lifecycle directories, absence of review, and no-op on v2 projects. It lacks details on authorization requirements or side effects, but given the absence of annotations, it provides sufficient transparency.

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 three sentences long, front-loading the core action and then adding implementation and usage details. Every sentence adds value without any 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?

Given the presence of an output schema (handling return values), no annotations, and two clearly documented parameters, the description adequately explains the tool's role in the v3 lifecycle. It could mention potential errors or return structure, but overall it is 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 description coverage is 100%, so the schema already documents both parameters. The description adds context about the tool's lifecycle but does not provide additional semantic detail for the parameters beyond what the schema offers. 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 tool's purpose: finishing an active task by transitioning it from active to done lifecycle state, with specific file movement details. It also distinguishes from siblings like approve_task by noting there is no review step.

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 this for tasks that do not require ADMIN approval,' providing clear usage context. It also notes that on v2 projects it is a no-op, which helps guide correct invocation. However, it does not explicitly name alternative tools like approve_task when approval is needed.

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

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

No annotations provided, so description carries full burden. Clearly describes it as a read-only listing operation with no side effects, and mentions resulting documentation deployment. Could be more explicit about idempotency but sufficient.

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?

Concise two-sentence structure with front-loaded purpose. Every sentence adds value, uses code formatting for clarity.

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?

Simple tool with one optional parameter and existing output schema. Description covers purpose, usage context, and ties to init_project, making it complete for agent use.

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 parameter 'lang' already has a detailed description. The tool description adds no further parameter information, so baseline 3 applies.

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

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

Clearly states it lists bundled preset teams and their role rosters, with a specific verb and resource. Differentiates from siblings like create_custom_team and init_project.

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

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

Explicitly says 'Useful before init_project', providing clear when-to-use context. Lacks explicit when-not-to-use or alternatives, but the specific use case 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 shows it is a read-only summary returning specific aggregates. It does not mention permissions or errors, but adequately discloses the output and purpose.

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, bolded title for quick scanning, front-loaded with purpose. Every sentence adds value without 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?

Given no parameters and an output schema present, the description is complete for a health check tool. It might benefit from stating it's a high-level overview, but the use case is clear.

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?

No parameters exist, so the description adds full meaning by detailing what the tool returns (risk levels, active tools, CRITICAL_TAG events). Schema coverage is 100% and description compensates completely.

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 returns aggregate statistics from governance event log: total calls by risk level, most active tools, and CRITICAL_TAG events. It distinguishes from siblings like list_governance_events by being a summary, fulfilling specific verb+resource.

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 mentions ADMIN attention for gaps, providing clear context for when to use. It does not explicitly contrast with siblings but the context of aggregate vs. detailed is 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 must communicate behavior. It correctly implies a read operation by calling it a 'snapshot', but it does not explicitly state that it is non-destructive or that no changes are made. The agent is left to infer safety.

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, front-loaded with the main purpose and then key details. Every sentence adds value, 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?

Given the presence of an output schema, the description adequately covers what the tool returns. It mentions all key aspects of the status. However, it could be slightly more explicit about it being a read-only operation.

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

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

The only parameter 'lang' is fully described in the schema (100% coverage). The description adds no additional information about parameter behavior beyond what the schema already provides.

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

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

The description clearly states the tool returns a 'concise status snapshot' and enumerates specific components: initialization, team/roster, counts of open tasks/reports/issues, and recent activity. This is distinct from sibling tools like list_tasks or get_available_teams which provide only partial data.

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

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

The tool is useful for quick overview, but the description does not explicitly state when to use it vs. alternatives, nor does it mention when not to use it. For example, if an agent needs detailed task info, it should use list_tasks instead.

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

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

No annotations are provided, so the description carries the full burden. It thoroughly details file creation, version changes, archival behavior on overwrite (via 'force'), and the four locations for protocol rules. It also notes the absence of deprecated v2 buckets, adding transparency about what is not created.

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 moderately long but well-structured with paragraphs for different concerns (topology changes, written files, protocol rules). It is front-loaded with the primary purpose. Some redundancy exists (e.g., archive behavior mentioned twice), but overall it is efficient for the complexity.

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

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

Given the complexity of initialization (multiple file types, locations, version migration), the description covers all essential aspects. It specifies directory structure, file deposition, archival on force, and output language. With an output schema present (confirmed by context signals), the lack of return value details is acceptable.

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 parameter descriptions are detailed (e.g., team values, language, force behavior). The description itself does not add new parameter semantics beyond the schema; it merely restates some behavior. 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 clearly states 'Initialize an FCoP project with a bundled preset team.' It lists specific actions: creating directories, writing config files, deploying team docs, and protocol rules. It distinguishes from the sibling tool 'init_solo' via a hint in the 'team' parameter description.

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 setting up an FCoP project, and the 'team' parameter documentation advises using 'init_solo' for solo mode. However, it does not explicitly state when to use this tool versus other initialization or configuration tools, and there is no direct contrast with siblings.

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

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

No annotations exist, so the description carries full burden. It details file creation, archiving on force, and version differences. It lacks mention of idempotency or error conditions when already initialized, but overall is 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 front-loaded with the purpose, but is somewhat lengthy with detailed bullet points. Every sentence adds value, but could be more concise without losing information.

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

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

Given the complexity (4 optional params, output schema exists), the description covers directory structure, file generation, archiving behavior, and version differences comprehensively. It leaves no obvious gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra context (e.g., role_label is for future use). It does not significantly enhance understanding 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 clearly states that the tool initializes an FCoP project in Solo mode, distinguishing it from init_project. It specifies the resource (FCoP project) and the mode, providing a unique identity.

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 Solo mode as one AI without dispatch, implying its use case. However, it does not explicitly contrast with init_project or specify when not to use it, leaving some ambiguity.

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

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

No annotations are provided, so the description must cover behavioral traits. It discloses that it catches specific violations but does not mention side effects, read-only nature, or error behavior. The examples help but leave gaps.

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

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

Two short, front-loaded sentences with a hyphen to introduce examples. Every word adds information; no fluff or repetition.

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 one parameter and an output schema, the description covers purpose and examples of input. Return values are left to the output schema, which is acceptable. Slight lack of guidance on edge cases or error handling.

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 a description for the single parameter. The description adds value by noting the parameter format matches 'read_task', aiding an agent familiar with that sibling tool.

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

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

The description clearly states 'Validate a task file against FCoP grammar' with specific examples of violations. It distinguishes from raw read operations but does not explicitly differentiate from sibling tools like fcop_check or fcop_audit.

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

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

The description implies use when deterministic validation is needed, contrasting with 'read_file+regex' agents. It provides context but lacks explicit when-not-to-use or alternative tool recommendations.

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 states the tool 'reads' the log and returns events, implying a read-only, non-destructive operation. It does not detail permissions, rate limits, or whether the operation is idempotent, but the basic behavioral trait 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 extremely concise: a bold header and two short sentences. Every word adds value, and key information is front-loaded. There is no redundancy or wasted text.

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

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

Despite lacking annotations, the description clearly explains the tool's purpose and output (risk classification). The existence of an output schema likely compensates for any missing details about return values. A minor gap is that it doesn't explicitly state the tool is safe/read-only, but it is strongly implied.

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 covers all three parameters with descriptions and defaults (schema coverage 100%). The description offers no additional semantic value beyond what the schema already provides, 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?

The description clearly states 'Read the append-only governance event log' and explains it returns 'recent tool-call intercept events' with risk classification. This distinguishes it from sibling tools like fcop_audit or fcop_check, which have different purposes.

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 says 'Use this to understand what actions agents have taken and their risk classification,' providing a clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare to 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?

No annotations are provided, so the description carries the full burden. It discloses the two behavior modes and the ordering of date shards (newest first). However, it does not mention whether the operation is read-only, pagination, or any rate limits.

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 cover the purpose and both usage modes. Every sentence adds value, with 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?

Given the simple one-parameter tool and the presence of an output schema (which presumably covers return fields), the description is sufficiently complete. It explains the two operation modes, though it could explicitly state read-only 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%, but the description adds meaning beyond the schema: it explains that supplying a date lists task entries, while omitting it lists shards. This provides context the schema alone does not convey.

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 lists the deep history archive and distinguishes between two modes: with a date (lists task entries) and without (lists available date shards). This sets it apart from siblings like list_tasks (current tasks) and read_history_task (single 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 clear context on when to supply the date parameter and what happens in each case. It implies usage for browsing history, but does not explicitly exclude alternatives like read_history_task for specific tasks.

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

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

No annotations are provided, so the description must carry the full burden. It only states it lists issues with optional filtering, lacking details on pagination, ordering, permissions, or effects on the system.

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 unnecessary words. It is efficient but lacks completeness, which prevents 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 complexity (5 parameters, output schema exists, many siblings), the description is too minimal. It does not explain return values, sorting, or pagination, leaving the agent underinformed.

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 description adds no additional meaning beyond the schema's parameter descriptions. The baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'issues' with optional filtering. However, it does not differentiate from sibling tools like list_tasks, list_reports, etc., which also list different resources.

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 provided on when to use this tool versus alternatives. The description only mentions optional filtering without specifying when it is appropriate or when to avoid using 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 full responsibility for behavioral disclosure. It only conveys that the tool lists and filters reports, omitting critical traits like pagination behavior, default status, case-insensitivity of filters, and whether the operation is read-only. The schema partially fills gaps, but the description fails to add meaningful behavioral context.

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

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

The description is extremely concise—a single sentence with no redundant words. It is well front-loaded and avoids any unnecessary elaboration, earning top marks for efficiency.

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

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

Despite having an output schema (not shown) and full parameter descriptions, the description lacks contextual completeness. It does not explain what a 'report' is in this system, when to use filters, or how this tool fits among siblings. For a 5-parameter tool with no usage guidance, the description is too sparse to be fully informative.

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 input schema already documents all parameters with descriptions. The tool description adds no extra meaning to parameters beyond stating that filtering is optional. Baseline of 3 is appropriate as the schema carries the load.

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 lists reports and supports optional filtering, but it does not differentiate what constitutes a 'report' relative to siblings like list_tasks or list_issues. The verb+resource is clear, but context is missing to distinguish from similar 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 provides no guidance on when to use this tool over alternatives such as list_tasks or list_issues. There is no explicit when-to-use or when-not-to-use information, leaving the agent to infer context from the tool name alone.

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

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

With no annotations provided, the description should disclose behavioral traits like authentication, rate limits, or pagination effects. It only says 'List REVIEW files, optionally filtered' without any additional behavioral context.

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

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

The description is extremely concise (one sentence) but lacks many details. It is not verbose, but under-specification reduces its helpfulness. Every word is functional but incomplete.

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 (mentioned but not shown), the description does not need to explain return values. However, it omits important context like default ordering, pagination handling, error conditions, or any filtering nuances, making it insufficient for effective agent use.

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

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

All 6 parameters are fully described in the input schema (100% coverage). The description adds no extra meaning beyond what the schema provides, so 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 clearly states it lists REVIEW files with optional filtering. It distinguishes it from other tools like read_review, though 'REVIEW files' is somewhat narrowly defined.

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

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

No guidance on when to use this tool versus alternatives (e.g., read_review for a single review, or other list tools). The description lacks context for when filtering or pagination should be applied.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only states that the tool lists tasks and can be filtered, but does not mention any behavioral traits like read-only nature, side effects, pagination defaults, or scope (e.g., tasks in current workspace).

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 at five words, front-loading the purpose. However, it is almost too terse; adding a bit more context (e.g., scope or default behavior) would improve clarity without harming 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?

Despite an output schema being present, the description lacks essential context such as the default status filter (defaults to 'open'), scope of tasks, and the relationship between parameters. The description is incomplete for a tool with six optional parameters and no annotations.

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

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

With 100% schema description coverage, the baseline is 3. The tool description adds no extra meaning beyond the schema; it merely mentions optional filtering. The parameter descriptions in the schema are self-sufficient.

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 explicitly states the action ('List') and the resource ('tasks'), which is clear. It also mentions optional filtering. However, it does not distinguish 'list_tasks' from sibling tools like 'list_governance_events' or 'list_reports', which also list entities.

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 such as 'read_task' (single task retrieval) or 'inspect_task' (detailed view). The description does not provide context for when filtering is appropriate or how it relates to other list operations.

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, description carries burden. It discloses the two types of workspaces and that metadata is provided. Does not explain authentication or edge cases, but provides reasonable transparency for a non-destructive read operation.

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

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

Three efficient sentences: purpose, nuance, and use case. No wasted words, front-loaded with key action.

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?

Tool is simple with one optional parameter. Though we don't see the output schema, its existence relieves description from detailing return values. Description covers behavior adequately.

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% for the single lang parameter, and description adds no additional meaning beyond what the schema already provides. Baseline score justified.

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?

Clearly states it lists workspace subdirectories with metadata, distinguishes between two types of workspaces (created by new_workspace vs hand-created), and states the use case for an at-a-glance view. Differentiates from sibling tools that list other entities.

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?

Implicitly tells when to use (for overview of workspaces), explains what it picks up. Does not explicitly state when not to use or give alternatives, but the context is sufficient for a simple list 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?

Without annotations, the description discloses that the tool writes a 'human_approval' sub-structure into the REVIEW frontmatter and returns the updated summary. It does not mention permissions or destructive actions, but covers the core 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 three sentences, front-loaded with the main purpose. It is concise, well-structured, and informative without extraneous 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?

Given the existence of an output schema and thorough input schema, the description provides sufficient context for the tool's workflow. It mentions the escalation loop and ADR-0026, leaving little ambiguity.

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 minimal parameter details; it mentions the 'approver' must be an agent with layer admin, but this is already in the schema. No additional meaning beyond 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 clearly states the tool records a human approval decision on a 'needs_human' REVIEW file, specifying the action and the context. It distinguishes from sibling tools like 'write_review' and 'read_review' by focusing on the approval step in the escalation loop.

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 indicates when to use: after a review has been set to 'needs_human' via 'write_review'. It provides clear context but does not explicitly state when not to use or mention alternative 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?

Discloses idempotency, that title/description are updated on duplicate calls, and that files are never wiped—key behavioral traits 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?

Concise, front-loaded with purpose, then convention, then idempotency. No unnecessary words.

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

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

Covers creation behavior, idempotency, file safety, and context of why workspace subdirectories are used. Output schema exists, so return values need no explanation.

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 already describes all parameters fully (100% coverage). Description adds minimal extra context about slug pattern and directory path, but does not significantly enhance parameter understanding.

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?

Clearly states it creates a workspace subdirectory under a specific path, distinguishing it from sibling tools like init_project or list_workspaces.

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

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

Explains when to use (to prevent project root clutter) and mentions idempotency, but does not explicitly list when not to use or compare with 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 provided, the description carries the full burden. It discloses the search location (history/) and the efficiency benefit of the date parameter. However, it does not explicitly state the tool is read-only, nor does it mention potential behaviors like error handling or rate limits. The action 'Read' implies non-destructive, but lacks explicit safety confirmation.

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 three sentences, each earning its place. The first sentence states the purpose, the second explains the search mechanism, and the third provides optimization guidance. No unnecessary words or redundancy.

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

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

Given the presence of an output schema, return value explanation is unnecessary. The tool is simple with 2 parameters (1 required). The description covers core functionality, search location, and optimization hint, making it sufficiently complete for an agent to invoke 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 schema already describes both parameters. The description adds value by explaining the effect of the date parameter ('restricts search to that date shard') and its performance benefit ('much faster'), which goes beyond the schema's simple description.

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

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

The description clearly states 'Read a task from the deep history archive.' It specifies the verb 'Read' and the resource 'deep history archive', distinguishing it from sibling tools like 'read_task' which likely read current 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?

The description provides guidance on when to use the optional date parameter for efficiency ('much faster'). However, it does not explicitly state when to use this tool versus alternatives like 'read_task' or 'list_history', missing explicit when-not or alternative suggestions.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It only states the basic action, omitting details such as error behavior (e.g., file not found), access requirements, or whether the read is local or remote.

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 very concise (one sentence), but this brevity comes at the cost of missing important details. While it earns its place by stating the purpose, it could be expanded with more structure (e.g., mentioning the parameter and 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?

Given that an output schema exists (so return values are defined elsewhere) and the tool is a simple read operation, the description is minimally functional. However, it lacks contextual details like report location or typical use in a workflow (e.g., reading after listing reports).

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% and the schema already describes the filename parameter, the tool description adds no additional meaning beyond redundantly mentioning 'report file'. It does not explain the dual nature (filename or task_id) already present in 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 ('Read') and resource ('report file'), clearly identifying the tool's action. However, it does not incorporate the schema's detail that the filename can also be a task_id, which would improve 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?

No guidance is provided on when to use this tool versus alternatives like list_reports (to find reports) or read_task (for tasks). The description lacks any context about prerequisites or decision criteria.

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

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

The description implies a read operation with no side effects, but does not mention any specific behavioral traits like authentication requirements or output format. Since no annotations exist, the burden is higher, but the output schema may compensate.

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

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

A single sentence that conveys the essential purpose without any extraneous words. Maximum conciseness.

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

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

For a simple read operation with one parameter and an output schema, the description is nearly complete. Lacks usage guidelines, but otherwise 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 the filename parameter. The description adds no significant new meaning beyond the schema's description.

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

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

The description clearly states the verb 'Read' and the resource 'REVIEW file', making the tool's purpose obvious. It distinguishes itself from siblings like write_review (write) and list_reviews (list).

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 provided on when to use this tool vs. alternatives such as list_reviews or read_task. The agent must infer usage from context.

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

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

The description implies a read-only operation with no side effects, which is consistent with a read tool. However, it does not explicitly state that the operation is safe or disclose any behavioral traits like caching, authorization needs, or error handling, especially given no annotations.

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

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

The description is a single concise sentence with no extraneous words, efficiently conveying the tool's 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?

Given the simple single-parameter input and the existence of an output schema, the description is largely sufficient. It could be improved by noting that the output contains the full task file content, but that is likely defined in 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?

The input schema already provides 100% coverage with examples and usage notes for the 'filename' parameter. The description only restates the tool's purpose and does not add additional meaning beyond what the schema provides.

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

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

The description clearly states the tool reads the full content of a task file, which is a specific verb+resource. However, it does not differentiate from sibling tools like 'inspect_task' and 'read_history_task', which likely have overlapping functionality.

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 provided on when to use this tool versus alternatives such as 'inspect_task' or 'read_history_task'. The description lacks context for appropriate usage.

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

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

With no annotations, the description carries the full burden. It discloses that the tool is ADMIN-only, overwrites files with force=True, archives old copies when archive=True, and warns about destructiveness when archive=False. It could further mention that it may overwrite local edits, but overall provides good behavioral context.

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

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

The description is well-structured with a clear header, a code block for file locations, and separate usage instructions. Every sentence adds value, and there is no redundancy or unnecessary detail.

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

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

Given the complexity of the tool and the presence of an output schema, the description covers the core purpose, usage context, and parameter interactions. It lacks information about error handling or success indications, but overall is sufficiently complete for an admin 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%, and the schema already provides detailed descriptions for each parameter. The tool description adds minimal additional meaning beyond restating the parameter behaviors, so it meets 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 clearly states the tool redeploys bundled FCoP protocol rules to the project, specifying it is ADMIN-only and listing the exact file locations. This distinguishes it from siblings like 'deploy_role_templates' which deploy different resources.

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 advises to run after upgrading fcop and mentions that fcop_report indicates when it's needed. It also includes a policy statement that agents must not invoke this tool, giving clear when-to-use and when-not-to-use guidance, though it lacks explicit 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 full burden. It discloses that the tool moves the task file from _lifecycle/review/ to _lifecycle/active/, appends a transition event, and is a recall mechanism. It also notes the v2 no-op behavior. Could mention authorization requirements beyond the default actor role.

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 two short paragraphs. The first sentence gives the main action. Every subsequent sentence adds necessary detail: lifecycle path, transition event, purpose, and version behavior. No redundant 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 lifecycle management and version differences, the description is quite complete. It covers the lifecycle transition, file paths, event logging, and v2 no-op. It could mention prerequisites like the task must be in review state, but overall it is adequate.

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, but the description adds valuable context: it explains that 'task_id' can be ID or full filename, that 'actor' defaults to ADMIN, and that 'note' is strongly recommended and mandatory in practice. This goes beyond the schema's detail.

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

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

The description clearly states the tool rejects/recalls a task under review, moving it from 'review' to 'active' lifecycle. It distinguishes itself from siblings like approve_task and archive_task by describing the specific lifecycle transition and mentioning it is the FCoP v3 recall mechanism.

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 a task under review needs rework by ADMIN. It explicitly notes that on v2 projects it is a no-op, providing important context. However, it does not explicitly state when not to use or list alternative tools for similar purposes.

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

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

With no annotations, the description carries the full burden. It discloses that the tool re-binds subsequent calls, mutates only in-process state, does not write to disk, and is safe to call while unbound. This provides good behavioral clarity, though it could mention if there are any side effects on existing bindings.

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 key purpose and structured into three paragraphs that each add value. It uses examples and backticks for clarity. While concise, it could be slightly tighter without losing information.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers purpose, usage context, behavioral details, and parameter semantics adequately. It is complete for a tool with one parameter and clear effects.

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 one parameter. The description adds meaning beyond the schema by specifying the expected contents of the directory (docs/agents/, .cursor/rules/) and clarifying it does not need to be an initialized project. This enriches the parameter's 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?

Description clearly states 'Pin the project root for this MCP session' with a specific verb, resource, and scope. It differentiates from siblings by being the only tool that sets the working directory, and it explains the symptom that triggers its use.

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

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

Provides clear context on when to use (when unbound_report shows wrong path) and what it does (no editing of mcp.json). It does not explicitly list alternatives or when not to use, but the context is sufficient for correct invocation.

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 provided, so description carries full burden. It discloses the file move, event appending, and v2 no-op behavior, going beyond basic action description.

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

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

Two sentences only, front-loaded with main purpose, no wasted words. Efficient and 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?

Simple tool with 2 params, output schema exists, description covers lifecycle transition and version behavior. Complete for the 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 coverage is 100%, with both parameters described in input schema. Description does not add additional details beyond schema, so 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?

Description states specific verb 'Submit' and resource 'active task', explicitly mentions lifecycle transition 'active → review', and distinguishes from siblings like approve_task, archive_task, etc.

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?

Clear context that this tool moves tasks from active to review, and notes it's a no-op on v2 projects. Lacks explicit exclusions or alternatives but provides sufficient 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 fully discloses behavior: it returns a command without executing it, explains why MCP servers cannot self-upgrade, and notes different install methods. This is comprehensive behavioral transparency.

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 (three sentences) and front-loaded with the main purpose. Every sentence adds value: purpose, limitation, and 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?

Given the tool's simplicity and the presence of an output schema, the description adequately covers the tool's purpose, behavior, and constraints without missing essential information.

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 fully describes the 'lang' parameter with a description of possible values. The tool description adds no additional semantics beyond what the schema provides, 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?

The description clearly states the tool returns the install-method-specific command to upgrade fcop-mcp, and distinguishes itself from sibling tools by focusing on upgrade commands rather than task or report operations.

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

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

The description explicitly states when to use (to get upgrade command) and what it does not do (does NOT run pip), providing context about safety and install methods. However, it does not explicitly list when not to use or mention 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 adequately discloses the dry-run nature and that no data is written to disk. Lists specific checks (Chinese characters, dashes, reserved names, duplicates), but does not describe output schema or what happens on success/failure.

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

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

Extremely concise: two sentences with no extraneous words. Each sentence adds essential information: what the tool is and how to use it.

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

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

Given the simple nature of the tool and 100% schema coverage with output schema present, the description covers purpose, usage, and key behavioral traits. Could mention what the output schema returns but that is optional.

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 already describes parameters. The description adds context by mentioning specific validation checks (Chinese characters, etc.) and reinforces that leader must be one of roles, adding value 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?

Clearly states verb 'validate' and resource 'custom team config', specifies it is a dry-run validation that checks for illegal role codes, and distinguishes from sibling 'create_custom_team' by indicating it should be used beforehand.

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 instructs to use before `create_custom_team` and explains benefits (catching errors without writing to disk). Does not provide explicit when-not-to-use, but the context is clear enough for a validation tool.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only states the action ('File an issue') without revealing side effects (e.g., file creation, overwrite behavior), permissions required, or other behavioral traits. This is insufficient for a write 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 extremely concise (one sentence), with no waste. However, it could benefit from slightly more detail to improve clarity 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?

Given the simple parameters and presence of an output schema (which handles return value description), the description adequately covers the location and action. It lacks some contextual details (e.g., file naming convention), but is mostly complete for this complexity level.

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 each parameter already has clear descriptions. The tool description adds no additional meaning beyond what the schema provides (e.g., how summary is used in the filename). 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 clearly states the action ('File an issue') and the location ('docs/agents/issues/'), making the purpose clear. However, it does not distinguish this tool from sibling tools like write_report or write_task, which could lead to confusion.

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 provided on when to use this tool versus alternatives (e.g., write_report or create_task). The description lacks any 'when-to-use' or 'when-not-to-use' context, forcing the agent to infer usage from the name alone.

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

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

No annotations provided, so the description carries full burden. It discloses the file creation path and naming, but does not mention side effects (e.g., overwriting, permission needs) or whether it updates the task status. Adequate but not comprehensive.

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 that efficiently state purpose and key detail (file path). No redundancy, front-loaded with the primary action.

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, return value explanation is unnecessary. The description covers purpose and output location. Missing details on error states or side effects, but sufficient for a straightforward file 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?

Schema coverage is 100% with good descriptions. The description adds value by explaining the report filename pattern and linking task_id to the source task, which goes 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 clearly states it writes a completion report for a task, specifies the file naming convention and location, and distinguishes it from sibling tools like write_task or write_issue.

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?

While the description implies use for creating completion reports, it does not explicitly compare to alternatives or state when not to use it. The tool name and context make it clear, but explicit guidance is missing.

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