lockstep

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

With no annotations, the description carries the full load and does much of it: it discloses that ack/approve binds an open decision, that the review is recorded in the audit trail regardless of verdict, and that the decision status is returned. It stops short of stating permissions required, idempotency, or what happens when the decision is not open, which keeps it from a 5.

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

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

Three tightly written sentences, zero waste, with the core action and its effect front-loaded before the sibling routing. Every clause earns its place.

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

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

For a three-parameter mutation with no annotations and no output schema, the description covers the action, its side effect on decision state, audit recording, and the return value (decision status). Only edge cases such as already-bound decisions or permission requirements are unaddressed.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the verdict default and the non-binding case. The description restates the verdict behavior but adds no syntax or format detail beyond the structured fields; 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?

The description opens with a specific verb and resource: 'Acknowledge a decision version.' It explicitly contrasts itself with siblings propose_decision and decisions, so an agent can distinguish it without opening any schema.

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

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

It names the exact triggering condition ('a decision proposed by someone else that is awaiting acknowledgement') and routes the agent to alternatives for the adjacent tasks: propose_decision for creating/changing and decisions for finding ids and versions. Nothing is left to inference.

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

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

With no annotations, the description carries the burden and explains the mutation target, the important default-all-unread behavior, the return value, and boundaries versus sibling tools. It does not mention permission requirements or whether marking read is reversible, so it is strong but not fully transparent.

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

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

Three concise sentences with the core operation front-loaded, followed by default behavior and sibling-tool routing. Every sentence adds useful selection or invocation 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?

For a single optional array parameter, no output schema, and no annotations, the description covers the action, default behavior, return value, and alternatives sufficiently for correct invocation.

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

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

Schema coverage is 100%, so the parameter is already documented. The description reinforces that omitting itemIds marks every unread item and clarifies session scope, but adds no syntax or format detail beyond the schema 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: mark inbox items as read by id. It also scopes the no-id behavior to this session's inbox and explicitly distinguishes itself from ack_decision and answer.

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 usage: pass ids to mark specific items, omit ids to mark every unread item. It also names alternatives for related actions, saying to use ack_decision for decisions and answer for questions.

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 load and does it well: it discloses this is a write ('records', 'marks the question answered'), that the record is permanent, and critically that there is no still-unanswered check so repeat calls create duplicate answers. It also states what is returned (answer id and status), covering the non-idempotency risk an agent would otherwise miss.

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 tight sentences, front-loaded with the purpose and effect before the sibling routing and the duplicate-call caveat. No filler, though the return-values clause could be trimmed slightly since it is minor relative to the rest.

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

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

For a 2-parameter mutation with no annotations and no output schema, the description supplies everything needed: what it does, what it writes, what it returns, when not to use it, and the duplicate-answer hazard. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including what the response text should look like. The description adds only the framing 'by its questionId' and nothing about format or validation beyond that, so the schema is doing the heavy lifting – baseline 3 is correct.

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

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

States a specific verb (answer) and resource (a question in the project's inbox), plus the full effect: records the response, marks the question answered, returns the answer id and status. It also explicitly distinguishes itself from the sibling 'ask', so an agent can route without opening the schema.

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

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

Explicitly names the alternative ('Use ask to raise a question') and the exclusion ('answer is only for replying to one'), which fully resolves the ask-vs-answer decision. The questionId requirement in the first sentence further anchors when this tool applies.

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 load and does disclose the key side effect: the question is delivered to recipients' inboxes and urgent elevates it, i.e. this is a notifying write operation. It also discloses the return payload (question id and status). It stops short of stating anything about permissions, rate limits, or whether the call waits for a reply.

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 short sentences, front-loaded with purpose, then mechanics, then the routing decision. Every sentence carries information, though the telegraphic fragments ('urgent flags it', 'Replies are recorded with answer.') read slightly clipped compared with the rest.

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 three-parameter, no-annotation, no-output-schema tool, the description supplies purpose, side effect, return shape, and the full ask/answer loop with the query alternative. Only the synchronous-vs-asynchronous question (does the caller wait for a reply?) is left unaddressed.

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

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

Schema coverage is 100% and each parameter's description already explains scope format, urgent default, and expected question content, so the schema does the heavy lifting. The description only echoes the existence of optional scope and the urgent flag without adding format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

Opens with a specific verb and resource ('Ask the project a question'), then states the delivery channel (project inboxes), the urgent flag behavior, and the return value (question id and status). It is clearly separable from siblings: 'query' is named as the non-notifying alternative and 'answer' as the reply path.

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 routing is given: 'Use for a question that needs a person or another team to reply; try query first, since it searches existing answers without notifying anyone.' It names both the condition for use and the condition that selects the sibling instead, plus points to 'answer' for the reply half of the loop.

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

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

With no annotations, the description carries the full burden and does it well: it discloses that the diff of tracked changes is uploaded to a Lockstep server (untracked files are excluded), that a 'skipped' status is returned unless hosted diff checks are on, and that findings are advisory rather than blocking. These are exactly the side-effect and outcome traits an agent needs before calling.

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 tight sentences, front-loaded with the purpose and scope, then the gating behavior, parameter note, and return shape. The parameter sentence is somewhat redundant with the schema but not wasteful enough to penalize heavily.

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 the upload behavior, the skipped-status path, the finding shape (file, line, rule), and the advisory nature — all important for a tool with no output schema. Minor gaps remain around required permissions or configuration for enabling lockstep checks, but the agent has enough to act correctly.

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

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

Schema coverage is 100% and the schema already documents `base` with its default of HEAD. The description only restates 'the optional base is the git ref to diff against', adding no format guidance or examples beyond the schema. Baseline 3 applies.

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

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

Opens with a specific verb+resource: 'Check the working-tree diff against accepted decisions.' It also names the sibling `decisions` for the adjacent read-the-rules task, so the agent can tell the two apart without opening either schema.

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

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

The description gives a clear context (working-tree diff checking) and routes the agent to `decisions` when it wants to read the decisions themselves. It doesn't state explicit when-not-to-use conditions or a workflow point (e.g. before commit), so it falls short of a 5.

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

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

With no annotations, the description carries the full load and does so well: it discloses that the note is accepted but not stored, that the task is set to both done and closed, that a status is returned, and that no assignee check occurs. Remaining gaps are idempotency (calling twice) and behavior on an invalid or already-closed taskId.

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?

Short and front-loaded: the action comes first, then the note caveat, then the behavior and the routing advice. Slight redundancy with the schema's own note description keeps it from being maximally tight.

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

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

For a simple two-parameter mutation with no annotations and no output schema, the description covers the write semantics, the no-op parameter, and the return value. Only edge-case behavior (errors, repeat calls) is left unstated.

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

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

Schema coverage is 100% and the schema already documents both parameters in detail, including that note is not stored. The description largely restates that, adding only the hint to put important content in notify or answer, which is already in the schema text. Baseline 3 applies.

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

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

States a specific verb and resource ('Mark a task closed by its taskId') and pins the scope to tasks created via delegate, which separates it from sibling tools like ack_inbox or ack_decision. An agent can tell what it accomplishes without opening the schema.

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

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

'Use for a task created with delegate' gives a clear trigger condition tied to a named sibling. It does not say when NOT to use it, e.g. whether it works on tasks from other sources or what to call instead for non-delegated items.

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 still declares 'Read-only' and, more valuably, discloses a coverage caveat: only dependencies registered via register_dependency or found by scanning appear, so results may be incomplete. It does not describe behavior for an unknown surface or result ordering, keeping it short of a 5.

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

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

Four short sentences, each carrying distinct information: purpose, safety profile, data-coverage limit, and routing guidance. The core purpose is front-loaded and nothing is repeated.

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 no output schema and no annotations, the description covers purpose, safety, data provenance, and the sibling alternative. It leaves the shape of returned repos (names, paths, relationship metadata) and the empty-result case implicit.

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

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

Only one parameter and schema description coverage is 100%, with the schema's own example ('http:GET /orders/:id'), so the schema does the heavy lifting. The description adds conceptual framing (a 'surface' lives in the dependency graph) but no syntax or format detail 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?

States a specific verb and resource ('List the repos that consume a surface') plus the data source ('the declared-dependency graph'), which is enough to distinguish it from siblings like whoowns. An agent can tell what it retrieves without opening the schema.

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

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

Gives an explicit usage trigger ('Use before changing a surface to see who is affected') and names the alternative for the adjacent question ('use whoowns for file owners'). Both when-to-use and when-to-use-something-else are covered.

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

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

With no annotations, the description carries the full burden and does well: it declares read-only behavior and enumerates the returned fields (id, scope, status such as open/binding, version, rule text, review fields). It omits pagination/result-size limits and any auth or permission notes, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the core action and scope, followed by return shape and then alternatives. Every sentence carries distinct information with no 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?

There is no output schema, and the description compensates by describing the returned decision fields and their possible statuses. The only meaningful gap for a list tool is pagination or result-size behavior, which is unmentioned.

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

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

Schema coverage is 100% and the single scope parameter is already documented with an example and the omit-to-list-everything behavior. The description only restates that the filter is optional, adding no syntax or matching detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("List the project's decisions") plus the filtering scope, and explicitly names two sibling tools it is not. An agent can distinguish it from query and check_decisions without inspecting any schema.

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

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

Gives explicit routing rules: use query to search by topic, use check_decisions to test a diff against decisions, and omit scope to list everything. Both the alternative and the condition that selects it are stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the side effect ('notifies the assignee through their inbox'), the lifecycle ('Creates an open task'), the fallback when no member matches the login, and the return shape ('task id and run state'). It does not mention permission/auth requirements or whether repeated delegation creates duplicates, which keeps it below a 5.

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

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

Front-loaded with the core action, then behavior, then routing in roughly priority order; every sentence carries information. Minor redundancy in re-explaining the assignee fallback already covered by the schema drops it one point.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers creation semantics, side effects, assignee fallback, and return values. Only durability/permission concerns are absent, which is a small gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter notes ('required to value is the assignee's GitHub login', 'optional refs') largely restate what the schema already documents, and it adds no format or constraint detail beyond the existing schema text.

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

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

States a specific verb and resource ('Create a task from a description, with optional refs') and immediately names the sibling tools it is not (complete for closing, ask for queries). An agent can distinguish it from ask/complete without opening any schema.

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

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

Explicitly routes to alternatives with conditions: 'Use complete to close it later; use ask instead if you only need an answer.' That is a clear when-to-use and when-not-to-use split against the two most confusable siblings.

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

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

With no annotations, the description carries the full burden: it does useful work by declaring "Read-only" and warning that constraints come back empty when the product layer is off. However, it says nothing about permissions, response shape, or what a "governed surface" item looks like, leaving meaningful behavioral gaps for a query tool.

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

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

Three tight sentences with the return content front-loaded, followed by the empty-result caveat and the usage trigger. Nothing is redundant and 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 single-parameter read with no output schema and no annotations, the description covers what is returned, the empty-state condition, and when to call it. The missing piece is any indication of response structure, which matters slightly given there is no output schema.

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

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

Schema coverage is 100% and the sole parameter is fully documented there, so the baseline is 3. The description's "capability, surface or text scope" echoes the schema's "Capability reference, surface or free-text scope" without adding format, example, or resolution rules.

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

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

States a specific verb ("Return") and a specific resource ("product constraints and governed surfaces ... plus project principles"), which is concrete enough to distinguish it from siblings like check_decisions or set_feature_context. It stops short of explicitly naming a sibling to contrast against, so it is clear but not fully differentiated.

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

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

"Use before building a feature to learn the product rules for it" gives an explicit trigger and timing, which is exactly the context an agent needs. There are no exclusions or named alternatives (e.g., when to prefer check_decisions), so it falls short of a 5.

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

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

With no annotations, the description carries the behavioral burden and does well by stating "Does not mark them read; use ack_inbox for that," which discloses the key side-effect boundary. It also scopes results to "this session's unread inbox items," but does not elaborate on ordering, freshness, or whether repeated calls have any other 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 two tight sentences, front-loading the core purpose and following with behavioral and alternative-use guidance. Every clause earns its place, with no repetition or 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?

Given the tool has no parameters, no output schema, and no annotations, the description is complete enough: it states what is listed, the scope, the non-marking behavior, and sibling alternatives. An agent has sufficient information to invoke it correctly without additional 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?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a parameterless tool is 4. The description does not need to compensate for schema gaps because the schema coverage is complete and no inputs exist.

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 and resource: "List this session's unread inbox items" and enumerates the item types (changes, questions, tasks, decisions, conflicts). It clearly distinguishes this tool from siblings by naming ack_inbox, query, and decisions as alternatives for different jobs.

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 not to use this tool: use ack_inbox to mark items read, query to search the ledger by topic, and decisions to list decisions. These are concrete alternatives tied to specific user intents, leaving little ambiguity for an agent choosing among siblings.

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

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

With no annotations, the description carries the burden well: it discloses the confirmation gating per risk tier, the conditional fan-out to dependent repos, and what the call returns. It stops short of auth/permission requirements, idempotency, or what happens if a waiting change is never confirmed.

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

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

Front-loaded with purpose in the first clause, then alternatives, then gating, then return shape – a sensible order with no filler. It is dense; the surface/delivery sentence partly restates the surface property description, which keeps it from a 5.

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?

Eight parameters but all fully described in the schema, and the description supplies what the schema cannot: the publish lifecycle, confirmation gating, delivery fan-out, and the return payload (change id, publish state, delivered count, impact) despite there being no output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema does not: surface plus contractDelta are 'optionally tied', and a present surface changes delivery behavior to dependent repos. It also reinforces the riskTier default/confirmation split, going beyond the per-field text.

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

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

Names a specific verb+resource ('Publish a change to the project's change feed') plus the beneficiary ('so other teams' agents see it'). It also differentiates itself from the two nearest siblings by name, so an agent can choose without opening any schema.

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

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

Explicitly states when to use this tool ('something that already changed or is about to') and routes the two alternative cases to ask and propose_decision. The riskTier sentence further defines the gating condition (owned publishes immediately; shared/contract wait).

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

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

With no annotations, the description carries the full burden and does well: it discloses optimistic concurrency, the explicit conflict failure mode, and the binding semantics that differ by scope kind. It stops short of stating permissions/auth needs or what the proposal returns on success.

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

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

Three tight sentences with no filler; the core action comes first, followed by the concurrency constraint and the lifecycle consequence. Every sentence carries information an agent needs.

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

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

For a 9-parameter mutation tool with no output schema and no annotations, it covers the risky parts well (versioning, conflicts, binding). The main gap is that nothing is said about what a successful call yields (identifier, resulting version), which an agent may need to follow up.

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 of the 9 parameters is already documented, including baseVersion's conflict behavior and capabilityRef's default. The description adds only the version-conflict angle already echoed in the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Propose a decision') and enumerates the decision types (rule, architecture, principle) plus the scope it applies to. It is clearly distinguishable from read-side siblings like decisions/check_decisions, though it never names those siblings explicitly.

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

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

Gives concrete preconditions for calling: baseVersion must match the current version, use 0 for a new decision, and a stale value fails with a conflict. It also explains the post-call lifecycle (owner-scoped bind immediately; shared ones stay open until acknowledged), which tells the agent what proposing actually accomplishes.

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

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

With no annotations provided, the description carries the full burden and does so well: it declares read-only behavior ('nothing is sent to anyone'), explains that `scope` boosts ranking rather than filtering, and states that it returns rows rather than an answer. It omits anything about result limits, pagination, or index freshness.

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

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

Three tight sentences, front-loaded with the verb and corpus, then the non-obvious scope semantics, then the safety and sibling routing. Nothing is padded or repeated.

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

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

For a two-parameter read tool with no annotations and no output schema, the description covers purpose, the counterintuitive ranking behavior, the row-level return shape, the read-only guarantee, and the alternative tool. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description's note that scope boosts ranking rather than filtering largely restates the schema's own wording, so it adds little beyond the structured field despite being accurate.

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

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

States a specific verb (search) over a specific corpus (decisions, changes, answered questions) for a natural-language question. It also distinguishes itself from the sibling `ask`, which handles the case where the ledger has no answer.

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 routes the agent to `ask` when no answer exists in the ledger and a teammate should respond, which is a real when-not rule. It gives no guidance relative to the other overlapping retrieval siblings (`check_decisions`, `decisions`), leaving that differentiation implicit.

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

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

With no annotations, the description carries the burden and discloses the key side effect that it writes local files, plus that it does not mutate server decisions. It also lists return fields, though it does not cover overwrite semantics or error behavior in detail.

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 action, then side effects and return values, then usage condition. Every sentence contributes useful information without unnecessary 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?

For a no-parameter tool with no output schema, the description is complete enough to call correctly. It explains the local write behavior, expected return fields, and the condition for 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?

The tool has zero parameters, and the description explicitly states that it takes no input. This matches the empty schema and avoids ambiguity, fitting the baseline for zero-parameter tools.

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

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

The description names a specific action and resource: downloading the compiled decision pack and rewriting the generated local decision-pack skill. It is clear enough to distinguish from a pure decision check, but it does not explicitly differentiate itself from siblings such as sync_skills.

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

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

It gives a clear invocation condition: call when decisions may have changed and the local skill is stale. It also clarifies that it does not change server-side decisions and takes no input, though it does not name alternative tools or explicit when-not-to-use cases.

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

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

With no annotations, the description carries the burden and does disclose key behaviors: declarations are idempotent ('Repeating the same declaration is harmless') and change delivery happens through notify and the inbox. It omits authorization/error behavior and return semantics, so it is strong but not complete.

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

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

The definition is front-loaded and appropriately brief, but it repeats the delivery concept twice ('changes ... are delivered to this repo' and 'Changes ... then reach this repo through notify and its inbox'). That redundancy keeps it from being maximally concise.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose, idempotency, downstream effect, and the inverse sibling tool. It leaves return/confirmation behavior and permission requirements unstated, but the essential calling context is present.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the optional nature of producedRepoId and repeats the producedSurface example but adds no syntax or validation details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Declare') and resource ('this repo consumes a surface'), gives a concrete example ('http:GET /orders/:id'), and distinguishes the tool from the inverse sibling tool 'consumers'. An agent can identify the operation without opening the schema.

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

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

It establishes the context for registering a dependency and points to 'consumers' for the inverse query, but it does not explicitly say when not to use this tool or compare it against notify/inbox alternatives. The guidance is clear but not exhaustive.

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 still declares 'Read-only' and discloses the conditional scoping behavior tied to feature context, which is the main non-obvious trait. It stops short of describing result shape or what happens when no feature context is set, so the behavioral picture is clear but not complete for a zero-annotation tool.

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

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

Two sentences, front-loaded with the resource and payload, followed by usage and alternatives. Every clause carries information: scope, safety, timing, and sibling routing, with no filler.

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

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

With no output schema and no annotations, the description must carry the burden, and it largely does by characterizing the briefing contents and scope. The remaining gap is return granularity or format, which an agent cannot infer, though this is minor for a simple read-only briefing call.

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

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

There are zero parameters, so the baseline is 4 and there is nothing parameter-level to explain. The description does add relevant context about an environmental input (the current feature context) that changes output, which is a useful substitute for parameter guidance.

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

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

States a specific verb and resource ('Return the continuity briefing for this session') and immediately defines the payload as 'what changed and what is binding,' which is far more informative than the tool name alone. It also names the scoping rule (current feature context when set), so an agent knows exactly what it will get.

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

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

Gives explicit timing ('at the start of a session or after being away') and routes two related needs to named siblings: inbox for unread items addressed to you, decisions for the full list. This is explicit when-to-use plus alternatives, with no inference required.

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

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

With no annotations provided, the description carries the full burden and largely meets it: it discloses that the tool writes local state plus a feature-context file tied to the git remote, and explicitly states it never contacts the server. It omits what happens when a context already exists (overwrite vs. merge) and whether a remote-less checkout degrades gracefully.

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 short sentences, front-loaded with the action and followed by effects, dependencies, and the trigger condition. Every sentence carries information, though the closing 'changes only local state' partly restates the earlier 'Writes local state'.

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?

One required parameter, no output schema, no annotations: the description supplies the side effects, downstream coupling, and invocation timing an agent needs. Only edge-case behavior on repeat invocation or missing git remote is left unstated.

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

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

Schema description coverage is 100%, so the single capabilityRef parameter is already documented in the schema; the description adds only the notion that the value becomes session-active and is inherited by later calls. That is useful context but not syntax or format guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Set the active capability reference for this session.' It also delineates scope ('for this session') and distinguishes itself from session-scoped siblings that merely read or refresh state, so an agent can identify it without opening the schema.

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

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

Explicitly says 'Call it when starting work on a feature', giving a clear trigger condition, and explains the downstream relationship to notify and propose_decision (they inherit it unless they pass their own capabilityRef). It stops short of naming when not to call it or how it interacts with refresh_decision_pack, but the usage context is unambiguous.

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

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

With no annotations, the description carries the full load and does well: it discloses that this mutates the local checkout ('Writes local files'), that effects are deferred until the next session, and that a not_enrolled status can be returned. It doesn't say whether existing/local skill edits are overwritten or whether the operation is idempotent, which matters for a file-writing tool.

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

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

Four short sentences, zero filler, with the core action front-loaded and the prerequisite, side effect, and alternative following in order of importance. Each sentence carries distinct information.

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

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

For a zero-param, no-output-schema mutation tool, the description covers prerequisite, side effects, timing, and the sibling alternative. The remaining gap is what a successful return looks like (counts of installed vs updated skills), which there is no output schema to fall back on.

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?

Zero-parameter tool, so baseline is 4, and the description confirms 'Takes no input,' which matches the empty schema. Nothing further is needed.

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

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

States a specific verb (sync) and a specific resource (managed organization skills) into a named target (this checkout). It also explicitly distinguishes itself from a sibling by saying refresh_decision_pack is for decisions, not skills, so an agent can route correctly 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?

Gives a hard prerequisite (must be enrolled via lockstep enroll, otherwise not_enrolled) and names an alternative tool for the adjacent use case. What it lacks is a positive trigger telling the agent when in a session to call sync_skills, though 'skills load from the next session' hints it should be early.

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 behavioral burden, and it does cover the two things an agent most needs: the operation is read-only and the result is empty when there is no snapshot or no match. It stops short of describing the shape of the owner values (users vs. teams, single vs. list) or any permission/snapshot-staleness caveats.

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 short sentences: what it returns, the empty case, the safety profile, then the routing hint. Nothing repeats and the core behavior is front-loaded.

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

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

For a one-parameter read tool with no output schema and no annotations, the description covers return semantics and the empty case, which is enough to call it correctly. Only the exact shape of the returned owners is left unspecified.

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 single required parameter that is fully documented with an example, so the schema does the work. The description adds only an indirect reminder that the path belongs to the repo, which is baseline-level value.

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

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

States a specific verb and resource: return the owners of a file path from the repo's CODEOWNERS snapshot. It also names the adjacent sibling 'consumers' and what that one answers instead, so an agent can distinguish the two 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?

Gives an explicit when ('use before asking or delegating to find the right person') and an explicit alternative with its selecting condition ('use consumers for who depends on a surface'). Routing between the two tools is fully resolved in the description.

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