Foremerge

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

Despite annotations only stating non-read-only/non-idempotent, the description goes far beyond them by disclosing that Foremerge re-checks every gate, that a failed gate changes nothing and returns named error codes, that success writes refs/foremerge/accepted/<changeset_id>, and that overriding gates via MCP is refused. This is comprehensively transparent about side effects and failure behavior.

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

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

The description is dense but every sentence carries load-bearing information: purpose, sequencing, gate criteria, side effects, error behavior, and override policy. The most important usage guidance is front-loaded, and the gate details are grouped logically.

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

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

For a state-changing tool with no output schema, the description fully explains preconditions, gate checks, success effects, failure modes, error identifiers, and the boundary of what MCP can do. An agent has enough to decide whether to call it and what to expect.

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

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

The schema already covers both parameters fully, so the baseline is 3. The description adds meaningful semantics for git_ref by explaining its fallback resolution order (publication ref, then worktree HEAD) and the constraint that it must resolve to the current worktree HEAD, which is not 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 and resource ('Accept a ChangeSet as done') and immediately names the higher-level purpose ('so other agents may build on it'). It also contrasts with record_commit, which is the later step once work lands, so an agent can distinguish this from sibling tools.

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

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

It explicitly says when to use the tool ('after run_verification passes'), when not to use it yet ('use record_commit later'), and how to handle conflicts via resolve_conflict and discard_work. It also tells the agent that gate overrides are refused over MCP and a human should be consulted, which is actionable routing guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint, and the description reinforces this with 'Read-only: nothing is stored' and adds the key ep heral nuance that findings carry ephemeral eph_ ids and are not recorded. It also discloses when block ing is true and that persisted conflicts are OPEN or COORDINATING. This substantially exceeds annotation coverage.

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

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

The description is dense and information-rich, yet each sentence carries a distinct purpose: purpose, read-only guarantee, two usage modes, return fields, and alternatives. There is no filler or repetition. The structure moves logically from 'what' to 'when' to 'how' to 'instead', keeping all critical facts front-loaded.

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

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

For a tool with no output schema, the description admirably covers return semantics (conf licts, checked intents, block ing flag, active policy), id formats, status filters, ephemer ality, and exclusions. An agent has enough context to know when to call it, how to invoke each mode, and what the results mean. Nothing important is missing.

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

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

Although the schema is fully described (100% coverage), the description adds critical semantic guidance beyond the schema: it explains that intent text with scopes is a what-if check against a specific status range, that intent_id alone pists only OPEN/COORDINATING conflicts, and that intent_id with non-empty scopes replaces the intents' scopes for that check only. This is far more than the schema alone 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 opens with a specific verb and resource: 'Ask whether planned work collides with other agents' active work'. It further distinguishes itself from sibling tools like record_assessment and resolve_conflict by naming them as alternatives for recording decisions. This makes the tool's identity clear and unique among its siblings.

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

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

Explicitly states when to use each mode: intent_id alone before publish_changeset and run_verification, intent text with scopes for a what-if check, and intent_id with replacement scopes. It also tells the agent which tools to use instead when the goal is to record a decision. This is exemplary usage guidance.

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

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

Goes far beyond annotations: discloses that claims never lock, that overlap still grants the claim and records a warning, that re-claiming renews the lease instead of adding a second claim, that the first claim moves the intent to CLAIMED, and that the result includes advisory_only: true. This fully describes side effects and semantics.

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

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

The description is dense but every sentence contributes: purpose, workflow position, locking semantics, renewal behavior, ownership/state constraints, and return payload. It front-loads the core purpose before diving into edge-case behavior.

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

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

For a stateful, advisory claim operation with no output schema and no idempotency hint, the description covers success behavior, failure/conflict handling, state transitions, expiry/renewal, and return contents. An agent has enough information to call it correctly and understand consequences.

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

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

The input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying that scopes must be those declared on the intent, by explaining the loose-by-name overlap matching, and by describing renewal behavior tied to lease_seconds. It does not add per-parameter syntax, but the schema already covers 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 states a specific verb and resource: claim semantic work on scopes of your own intent for a limited time. It also places the operation in a workflow (after publish_intent and record_assessment, before start_work) and contrasts it with start_work by saying claims are advisory and non-locking.

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 gives the when-to-use context: 'Use this after publish_intent and record_assessment, and before start_work.' It also states constraints (only the intent's owner, only while intent is INTENT/CLAIMED/IN_PROGRESS) and tells the caller to use the intent's declared scopes, which routes the agent away from inventing scopes.

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 goes well beyond the uninformative all-false annotations, disclosing that the message is appended to a durable log with status UNREAD, that it does not interrupt or control the recipient, that linking a conflict_id moves it from OPEN to COORDINATING, and that no MCP tool reads messages. It also states the return value includes the stored message and its msg_ id.

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 longer than typical but every sentence carries distinct information: purpose, trigger, follow-up action, state transition, durability, non-interruptive nature, and return value. It is deliberately structured and front-loaded with the core operation, with no filler 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?

Despite lacking an output schema, the description explicitly states what is returned. It covers the integration with sibling tools, the state change on conflict_id, the durable status semantics, and the limitation that only the CLI can read messages. This is a complete briefing for a tool with this complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds a bit of contextual meaning (e.g., conflict_id linking moves the conflict, eph_ ids are rejected), but most parameter semantics already appear in the schema, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Send a stored message to another registered agent,' and immediately states the purpose—'to agree how two overlapping pieces of work should coexist.' It also differentiates from siblings by referencing check_conflicts and resolve_conflict, clarifying this tool is for the message-sending step, not conflict detection or resolution.

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

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

Explicit guidance is given: 'Use it when check_conflicts or related_work shows a clash you need the other agent to act on.' It also explains the follow-up flow with resolve_conflict and names the message id, and notes that the recipient reads via CLI since no MCP tool reads messages. This fully covers when and how to use the tool relative 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?

The description goes well beyond the destructiveHint annotation by specifying exact behavioral effects: setting intent to DISCARDED, releasing active claims, dismissing OPEN/COORDINATING conflicts, preserving history, and preventing resumption. It also discloses ownership and state restrictions, and notes the return value, giving the agent a complete mental model of side effects.

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

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

The description is a single dense paragraph, but every sentence contributes meaningful operational detail: usage context, state effects, side effects, restrictions, return value, and the alternative tool. It is appropriately front-loaded and not padded, though slightly longer than minimal.

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

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

For a state-mutating tool with no output schema, the description covers all necessary context: valid states, ownership, side effects on claims and conflicts, irreversibility, event log behavior, and how to proceed instead. Nothing an agent needs to decide whether and how to call it correctly is missing.

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

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

Schema coverage is 100%, with each parameter (reason, agent_id, intent_id) already documented clearly. The description adds context that reason is recorded and that only the owner can discard, but this mostly reinforces schema information rather than supplying substantial new meaning. 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 abandons one of your own intents with concrete examples (duplicate, work taken over), and explicitly contrasts it with resolve_conflict. It names the resource (intent) and the primary effect (set to DISCARDED), so an agent can distinguish it from siblings without ambiguity.

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

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

The description gives explicit when-to-use guidance: for unfinished intents that are duplicates or taken over by another agent. It also names the alternative tool (resolve_conflict) and states when not to use this tool, such as ACCEPTED, COMMITTED, or already DISCARDED intents, plus ownership requirements.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld=false, and the description reinforces this with 'Read-only.' It also adds meaningful behavioral detail beyond the annotations: accepted_commit is pinned at acceptance and never changed, and integration_commit is set by record_commit. No contradiction with annotations is present.

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

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

The description is information-dense and well-structured: operation and target first, then what can be checked, then read-only status, then routing to alternatives. Every sentence earns its place, and no filler or redundant restating of the title appears.

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

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

For a single-parameter read tool with full schema coverage and comprehensive annotations, the description fully covers what an agent needs: what the tool returns conceptually (status, fingerprint, provenance) and how to obtain an id. The absence of an output schema does not create a material gap because the description names the fields the agent should expect.

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

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

The schema covers 100% of parameters with a clear description of id, so the baseline is 3. The description adds useful parameter context by explaining how to find an id: status lists qualifying ChangeSets and query_work shows each intent's latest one. This exceeds the schema's minimal id 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 uses a specific verb-resource pair: 'Read one ChangeSet by id', and clearly distinguishes it from siblings by stating what it is not for: 'Use get_intent for the work item itself.' An agent can tell this tool apart from get_intent, status, and query_work without inspecting schemas.

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

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

It explicitly states when to use this tool: to check ChangeSet status, fingerprint, and commit provenance. It also names alternatives and when they apply, including get_intent for the work item, status for finding PROVISIONAL/VALIDATED/ACCEPTED ids, and query_work for each intent's latest ChangeSet.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It goes beyond annotations by disclosing the return shape (conflict counts/ids, status enum, scopes, depends_on) and noting that severity requires check_conflicts.

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 dense sentences with zero filler. The core purpose is front-loaded, followed by return details and sibling routing. Each sentence contributes distinct value.

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

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

For a single-parameter read tool with strong annotations and explicit sibling routing, the description covers the purpose, return contents, safety profile, and alternatives. No critical information an agent needs is missing.

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

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

The schema already fully documents the single id parameter with format 'int_...'. The description mentions reading by id but adds no new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Read one intent by id') and enumerates exactly what is returned: owning agent, OPEN/COORDINATING conflict count and ids, status, scopes, and depends_on. It also distinguishes itself from query_work and status explicitly.

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

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

Provides clear when-to-use context ('before assessing someone else's related work') and explicitly routes to alternatives: query_work for searching by agent/status/scope and status for everything at once. This leaves little ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description reinforces read-only behavior and adds the detail of registration order, which goes beyond the annotations. It doesn't contradict annotations and provides useful context about the returned data.

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

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

The description is efficient with no fluff. It front-loads the purpose, then provides usage guidance in separate short sentences. Each sentence adds value: purpose, read-only/no-args, usage for coordinate_with_agent, and usage for status. No redundant text.

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

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

Given the tool has no output schema, the description compensates by listing all returned fields and their order. It also covers a primary use case (finding agent ids) and mentions the alternative (status). For a simple read-only list tool, nothing essential is missing.

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

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

The tool has zero parameters and the schema is empty, so there is nothing to explain. The description explicitly notes 'takes no arguments', which is helpful confirmation. Baseline for 0 params is 4, and this description meets 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 clearly states the tool lists every registered agent with a specific set of fields (id, name, model, capabilities, worktree, Git branch/head, status). It distinguishes from siblings by noting it's a full listing, unlike status which focuses on active agents. The verb 'List' and resource 'registered agents' are explicit.

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

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

The description gives explicit guidance: use it to find agent ids before coordinate_with_agent, and use status for active agents alongside current work. This differentiates it from the status tool and provides a clear when-to-use and when-not-to-use scenario.

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 discloses significant side effects beyond the annotations: it snapshots the worktree, stores a fingerprint, starts the ChangeSet as PROVISIONAL, marks old ChangeSets SUPERSEDED, resets verification, and explicitly notes 'Git itself is not modified.' It also explains the return value, which is important because there is no output schema.

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

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

Every sentence carries distinct information: purpose, placement in workflow, snapshot/fingerprint behavior, file/symbol inference, state transitions, republish semantics, authorization constraints, Git safety, and return value. Despite its length, it is front-loaded with the most decision-relevant facts and contains no filler.

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

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

The tool has 13 parameters, nested objects, and no output schema, yet the description covers return values, state transitions, side effects, ownership rules, and workflow ordering. Combined with the fully documented input schema, an agent has everything it needs to decide when to call and what to expect.

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 13 parameters thoroughly. The description adds workflow context around files/symbols inference and defaults, but most of that is also present in the parameter descriptions. This meets the high-coverage baseline without adding substantial new per-parameter meaning.

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

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

The description opens with a specific verb and resource: 'Record a finished unit of implementation for your intent so it can be verified and accepted.' It clearly positions the tool in the workflow relative to siblings by saying 'after check_conflicts and before run_verification', leaving no ambiguity about what this tool does or how it differs from adjacent 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?

It gives explicit when-to-use guidance: 'once the change is committed in your worktree, after check_conflicts and before run_verification.' It also states preconditions and restrictions: only the intent's owner may publish, and only while the intent is in specific states. This is strong, actionable routing information.

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

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

Annotations are all false, providing minimal safety signals. The description carries the full behavioral burden and delivers: it states the intent is stored with status INTENT, compared against all active intents, returns the intent ID, detected conflicts, and related_work with asserted vs candidate semantics. It also explains side effects on the coordination graph via depends_on, all without contradicting the 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 dense but every sentence earns its place: it states the purpose, positions the tool in the workflow, explains the return semantics, and gives the alternative. It is front-loaded with the core purpose and avoids redundancy. 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 complexity (7 params, nested scopes object, no output schema), the description is remarkably complete: it covers the intent lifecycle, return structure (intent ID, conflicts, related_work with asserted/candidate logic), and the required next steps. It also clarifies the depends_on parameter's role in the coordination graph and references the alternative tool. An agent has everything needed to call it correctly and integrate it with the surrounding workflow.

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 every parameter is well-documented in the schema itself. The description does not add new parameter-level meaning beyond what the schema already provides—it reinforces the purpose of scopes (conflict detection) but that is also stated in the schema's scopes description. Thus a baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Announce') and a clear resource ('work you are about to do, and the scopes it will change'), immediately stating the tool's purpose. It distinguishes itself from siblings by explicitly positioning it as 'the first call for every task, after register_agent' and naming check_conflicts as a what-if alternative.

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

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

It gives explicit when-to-use guidance: 'before editing any code' and 'the first call for every task'. It also prescribes the follow-up sequence (record_assessment, claim_work, start_work) and clearly states when NOT to use it, directing the agent to check_conflicts instead for a non-storing what-if check.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's 'Read-only' phrase is redundant but harmless. It adds genuine behavioral value beyond annotations by disclosing the result shape (joins intent to agent, claims, latest ChangeSet, dependent intent ids, and OPEN/COORDINATING conflict counts), array capping by limit, and the surprising default that with no filters it returns intents of every status including finished ones.

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 focused sentences with zero filler: purpose and examples, result shape and safety, default behavior and sibling routing. The most decision-relevant information (what it does, how results look) is front-loaded, and the sibling routing closes the description. Every sentence earns its place.

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

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

For a complex query tool with no output schema, the description compensates well by describing the joined result shape, the capping behavior, and the unfiltered default. The exhaustive schema covers parameter semantics, so the only gap is exact output field names/types, which the narrative join description largely mitigates. Minor omissions like pagination details are covered by the limit parameter's schema description.

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

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

Schema coverage is 100%: limit, status, agent_id, and the nested scope object all have thorough descriptions, including the loose symbol-matching caveat. The description reinforces the semantic mapping of filters to questions (owner/status/scope) but adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Search intents by owner, status or scope') and illustrates the purpose with concrete questions ('who is changing this symbol, or which work still has open conflicts'). It also names the siblings it is not ('Use get_intent when you already have an id, and status for a grouped overview'), so an agent can distinguish it from confusable read-only tools without opening schemas.

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

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

The description explicitly routes the agent to alternatives with the triggering condition: 'Use get_intent when you already have an id, and status for a grouped overview of everything at once.' It also embeds usage signals via the example questions and states the default no-filter behavior, which tells the agent when this tool is appropriate versus when a narrower lookup is better.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden and meets it: append semantics ('Each call appends a new assessment rather than replacing an earlier one'), non-mutation of statuses ('changes no statuses: it does not open, resolve or dismiss conflicts'), an ownership check, and the return shape ('Returns the stored assessment with its asm_ id'). These behaviors go well beyond what the annotation flags convey and do not contradict them.

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?

Seven sentences, each earning its place: purpose, verdict semantics, timing, side-effect disclosure, follow-up routing, ownership, and return value. The purpose is front-loaded in the first sentence, followed by the workflow constraint. There is no filler, no repetition of schema text, and the level of detail is proportionate to the tool's 6-parameter workflow 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?

Despite having no output schema, the description discloses the return value ('Returns the stored assessment with its asm_ id'). It covers the full call envelope: when to call, how often, what side effects occur (appended, no status changes), who may call (owner only), and what to do next. For a 6-required-parameter workflow tool with two enums, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow meaning the schema cannot: 'deciding what that means is yours' tells the agent the verd_ict parameter is a judgment call on foremerge's overlap data, and 'Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work' explains the intent of the action enum. It doesn't redundantly restate parameter docs, only enriches them, justifying a point above baseline.

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

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

The description states a specific verb and resource: 'Record what you concluded about one entry from related_work.' It distinguishes itself from siblings by explicitly framing what it is not: 'it does not open, resolve or dismiss conflicts,' and by routing follow-up action to coordinate_with_agent, resolve_conflict, and discard_work. An agent can tell it apart from publish_intent, check_conflicts, and resolve_conflict without opening their schemas.

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

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

Timing is explicit: 'Call this once per related intent, after publish_intent and before you write code.' Ownership is stated as a precondition: 'Only the intent's owner may assess it.' Alternative routing is named directly: 'Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work as needed.' Nothing about when to invoke this tool is left to inference.

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

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

The description discloses the failure mode (TARGET_DIVERGED), side effects on success (stores integration_commit, moves ChangeSet to COMMITTED, returns updated ChangeSet), and the non-destructive behavior toward accepted_commit. Since annotations only give false safety hints, this detailed behavioral context is essential and well provided.

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?

Every sentence earns its place: purpose, sequence, failure condition, success effects, preservation of accepted_commit, and a limiter on what the tool does not do. It is compact yet information-dense, with no redundancy.

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

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

The description is complete for invoking the tool correctly, covering prerequisites, ordering, error conditions, return value, and side effects. Even without an output schema or meaningful annotations, the agent has enough context to know when and how to call record_commit.

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

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

The schema already describes both parameters with 100% coverage. The description adds important relational context: git_ref must contain the accepted commit in its history or the call fails. This goes beyond the schema's basic definitions and helps the agent understand the meaningful constraint between changeset_id and git_ref.

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 where accepted work landed after a merge, naming both the action and the resource. It distinguishes itself from siblings like accept_changeset by explaining it is used last, after acceptance and merging, and explicitly says it does not merge or push.

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

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

Explicit workflow guidance is provided: 'Use it last, after accept_changeset and the merge.' It also states the precondition that the commit must contain the accepted commit in its history, and clarifies that Foremerge does not merge or push anything itself, preventing misuse.

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?

Beyond the annotations, the description discloses important non-obvious behaviors: every call creates a new agent record even for a repeated name, a warning is returned when an active same-name/worktree agent exists, invalid worktree paths are rejected with INVALID_INPUT, and the response includes the agent plus warnings. These details are significant for correct invocation and are not visible from annotations alone.

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 dense but every sentence adds essential information: purpose, call timing, non-idempotence, warning conditions, validation behavior, and return value. It is longer than average but justified by the need to explain branching behavior and constraints. Slight restructuring could improve scannability, but nothing is wasted.

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

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

For a registration tool with no output schema, the description is remarkably complete: it covers lifecycle timing, idempotency caveats, validation failures, response contents, and relationship to other tools. An agent has enough information to call it correctly and interpret the result without additional investigation.

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 parameter descriptions already cover all four parameters at 100% coverage, providing a solid baseline. The description adds meaningful extra context for worktree by stating it must be inside the bound repository and is otherwise rejected, and clarifies that the worktree records Git branch and head. This goes beyond the schema without needing to repeat every parameter.

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

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

The description states a specific action ('Register yourself as a participant') and the concrete resource produced ('the agent id every other write tool needs'), immediately distinguishing it from sibling tools like list_agents or publish_intent. It clearly communicates the tool's central role in the workflow.

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

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

The description explicitly says to call it once at the start of each session and before publish_intent, providing clear ordering. It also warns about calling it again for the same name/worktree, which tells the agent when reusing the tool may not be appropriate. This is strong, actionable 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 only generic annotations (all false), the description carries the full burden and does so thoroughly. It discloses that agreement and message ids are not verified, that either party may resolve alone, the state transition to RESOLVED, the effect on both intents' acceptance gates, that code is not changed, failure conditions, and the return value. This goes far beyond what annotations provide.

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 information-dense yet every sentence earns its place: purpose, access constraint, safety warning, alternatives, side effects, failure mode, and return value. It is front-loaded with the core purpose and avoids filler, making it easy for an agent to scan and apply.

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 mutation semantics, the lack of an output schema, and minimal annotations, the description is complete. It covers the state change, failure conditions, constraints, and what is returned. An agent has enough information to invoke the tool safely and correctly without needing additional details.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description adds some operational context (e.g., only a party may resolve, decision recorded under agent id), but it does not materially extend parameter meaning beyond what the schema's property descriptions already state. Baseline 3 is appropriate.

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

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

The description states a specific action ('Record an audited resolution decision') on a specific resource ('durable cfl_* conflict') and explains the goal ('so blocked work can proceed'). It also differentiates from discard_work, making the tool's unique role unmistakable.

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

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

It explicitly tells the agent when to use the tool ('resolve only after the other party agrees'), which tool to use first ('Use coordinate_with_agent first'), and which alternative to choose instead ('discard_work instead when one side is simply dropping its work'). This is clear, actionable guidance with exclusions and 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?

Annotations provide no hints (all false), so the description carries the full burden and excels. It discloses side effects: may create generated files, moves state to VALIDATED or returns to PROVISIONAL, specific failure modes (STALE_CHANGESET, CHECK_FAILED), fingerprint requirements, and the registry timeout. This goes well beyond what annotations offer.

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?

Though lengthy, every sentence earns its place: purpose, usage timing, constraints, error conditions, state transitions, and return value are all covered. Front-loaded with purpose and usage, structured logically. No filler.

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

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

For a state-changing verification tool with error conditions and a return record, the description is complete. It covers prerequisites (fingerprint match), timing relative to siblings, error semantics, state outcomes, and the returned validation record. An agent can invoke it correctly without further info.

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 both parameters fully (100% coverage) with descriptions including format and state constraints. The description reiterates the changeset state requirement but adds no new parameter-specific 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 states a specific verb ('run') and resource ('one named check from the trusted Foremerge registry'), and explicitly differentiates from siblings by noting it is for verification between publish and accept, and that raw commands are not accepted. An agent can clearly identify this as the verification 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?

Explicitly states when to use: 'Use it after publish_changeset and before accept_changeset; acceptance relies on this result, not on tests you report yourself.' Also says raw commands are not accepted, guiding away from any alternative that might accept free-form commands. No 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?

Annotations provide no positive hints (all false), so the description carries the burden. It discloses the state machine transition, failure conditions ('fails in any other state, or if you do not own the intent'), scope ('does not create or renew claims'), and return value format. It does not mention reversibility or other side effects, but the state change itself is clearly described.

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: purpose first, then usage timing, then state behavior, then exclusions, then return value. Every sentence earns its place and the most critical information (what and when) is front-loaded.

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

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

There is no output schema, so the description explains the return value ('Returns the updated intent with open_conflicts, the count and ids of its OPEN or COORDINATING conflicts') and provides a follow-up action. It covers state machine, failure conditions, and excluded behavior, making it sufficient 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 is 3. The description adds meaning beyond the schema by explaining that intent_id must be in CLAIMED state (though the schema already says 'Your CLAIMED intent') and by clarifying the ownership consequence ('fails... if you do not own the intent'). It also states 'does not create or renew claims,' which clarifies what the parameters do not imply.

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

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

The description opens with a specific verb+resource: 'Mark your claimed intent as being implemented.' It immediately distinguishes itself from claim_work by stating it 'moves the intent from CLAIMED to IN_PROGRESS' and explicitly noting it does not create or renew claims, so an agent can tell it apart from its sibling tools.

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

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

Explicit guidance: 'Call it after claim_work, immediately before you begin editing code.' It names the alternative for claim creation/renewal ('use claim_work for that') and recommends a follow-up action ('check their severity with check_conflicts'). This fully covers when and when not to use the 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by stating it is a single consistent read and enumerating the exact content included, which helps the agent understand what the returned picture covers without an output schema.

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

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

The description is front-loaded with the core capability and content list, then adds usage guidance and alternatives. Every sentence serves a distinct purpose: what, safety, when, and what else to use.

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 no-argument read tool, the description completely specifies what the result includes, its consistency property, and when to call it. It also points to sibling tools for filtering and detail, so an agent has enough context to choose 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?

There are zero parameters, and the description explicitly says 'takes no arguments,' leaving no ambiguity. The schema fully covers parameter semantics, and the description reinforces that no arguments should be supplied.

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 purpose: get the whole coordination picture in one call, enumerating active agents, intents grouped by lifecycle status, claims, conficts, and ChangeSets. It also differentiates from siblings by point out query_work for filtering and get_intent/get_changeset for detail.

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

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

It explicitly says when to use it: orient at session start or before choosing work. It also names alternatives for other needs: query_work for filtering and get_intent/get_changeset for single item detail, making routing clear.

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