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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing: not what permissions are required, not what "versioned" means operationally, and not whether the created item is immutable or drafts a new revision. It states a mutation but gives no side-effect context.

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

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

The single sentence is efficient and front-loaded with the verb and resource, with no filler. But it is terse to the point of under-specification, so the brevity does not fully earn its place given the missing information.

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

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

For a mutation tool with no annotations and 0% parameter description coverage, the description is too thin. The existence of an output schema means return values need not be explained, but preconditions, the meaning of "versioned," and parameter intent are all absent.

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

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

Schema description coverage is 0%, so the description is responsible for explaining the three parameters, and it mentions none of them. Parameter names like title and spec are somewhat self-evident, but role (with a default of "product") and spec are ambiguous and remain unexplained in both schema and 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 pairs a specific verb ("Create") with a specific resource ("versioned work item"), so an agent knows exactly what operation is performed. However, it offers no differentiation from the siblings that also involve work items (list_work_items, update_work_item, handoff_work), so it stays short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The only implicit signal is that "create" is distinct from the sibling update/list tools, which the agent must infer on its own.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it doesn't say whether this is a read-only check or mutates gate state, whether it blocks a handoff or release decision, what permissions are needed, or how the 'current revision' is resolved. For a gate-evaluation tool with zero annotation coverage this is a substantial gap.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity reflects under-specification rather than disciplined concision.

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 presence of an output schema relieves the description of explaining return values, but everything else is missing: parameter meaning, read-vs-write nature, gate outcome semantics, and how it relates to the evidence and release-decision siblings. Given two required undocumented parameters and no annotations, this is inadequate.

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

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

Schema description coverage is 0% for both required parameters. The description never mentions work_item_id and gives no explanation of required_kinds — which is the central concept of the tool (which evidence kinds count toward the gate). At most it vaguely implies the existence of evidence kinds, adding nearly nothing over the bare 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 names a specific verb ('Evaluate') and resource ('QA gate') and states the condition being checked (all passing QA evidence on the current revision). However, it does not distinguish this from siblings like record_evidence or record_release_decision, and 'current revision' is never defined even though no revision parameter exists.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., evidence must be recorded first), and no reference to alternative tools such as record_evidence or record_release_decision. The agent must infer the workflow context entirely from the name.

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

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

With no annotations, the description carries the full behavioral burden, and 'Read' does imply a non-mutating operation. It usefully signals that the response is an aggregate of several artifacts (spec, revision, evidence, handoffs), which is real behavioral context, but it says nothing about scoping, permissions, or whether the read is cached or live.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though terse enough that it could have absorbed a routing clause without becoming bloated.

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

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

Because an output schema exists, the return values need not be explained, and the description does list the artifact categories returned. What remains missing is the linkage to the required work_item_id and any signal of when this read is appropriate, so it is adequate but not complete for a context-gathering tool.

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

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

Schema description coverage is 0%, so the sole required parameter 'work_item_id' is undocumented in both schema and description. The description alludes to a single item's context but never names or explains the identifier, leaving the agent to infer the parameter's 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 gives a specific verb ('Read') and enumerates the resources returned (spec, revision, evidence, role handoffs), so the agent knows this is a composite read of a work item's state. It is clearly distinct from the write siblings (create_work_item, update_work_item, record_evidence), though it never explicitly positions itself against list_work_items.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the read step preceding updates or handoffs, which is guesswork rather than instruction.

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

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

No annotations are provided, so the description carries the full burden. 'Record' implies a mutation, and 'tied to the current revision' hints at concurrency/optimistic-locking behavior, but the description never states whether it requires a matching revision, what happens on conflict, whether the handoff is idempotent, or what permissions are needed.

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

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

A single front-loaded sentence with no wasted words. However, the brevity reflects under-specification rather than disciplined conciseness for a 5-parameter mutation.

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

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

An output schema exists so return values need no explanation, but for a 5-required-parameter mutation with zero annotation coverage and zero schema description coverage, the description leaves critical behavioral and parameter context 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 0% across 5 required parameters. The description indirectly accounts for from_role/to_role ('role-to-role') and expected_revision ('current revision'), but work_item_id and note are left entirely undocumented in both schema and 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?

States a specific verb ('Record') and resource ('role-to-role handoff') with a scoping detail ('tied to the current revision'), which distinguishes it from siblings like record_evidence and record_release_decision. It does not explicitly name a sibling alternative, but the action and object are unambiguous.

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

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

There is no guidance on when to hand off work versus recording evidence or updating a work item, and no prerequisites or exclusions are given. The agent must infer the usage context entirely.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It hints at a read-only listing and names the returned fields, but says nothing about scope (all work items vs. a subset), pagination, ordering, or the fact that no parameters/filtering are accepted.

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

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

A single front-loaded sentence with no wasted words; the verb and the returned fields come first. Nothing extraneous is included.

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

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

An output schema exists, so the description need not explain return values, and the zero-parameter schema is trivial. The main gap is the absence of annotations, leaving the read-only/side-effect profile implicit rather than declared.

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 per the rubric the baseline is 4. There is nothing further for the description to disambiguate about arguments.

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

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

The description states a specific verb (List) and resource (work items) and names the returned fields (IDs, titles, current revisions), so its function is unambiguous. It does not explicitly distinguish itself from siblings such as get_context, but the read-only listing intent is clear.

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

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

There is no statement of when to use this tool versus alternatives like get_context, nor any mention of prerequisites, scope, or exclusions. Usage is only implied by the word 'List'.

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

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

With no annotations, the description carries the full behavioral burden. 'Append' hints at append-only/immutable semantics and 'current revision' hints at optimistic-concurrency checking, but the description never states what happens on a revision mismatch, whether the record is mutable, permission requirements, or side effects.

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

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

A single front-loaded sentence with no filler, and the key scoping constraints (revision, hash, environment) come first. It is efficient, though arguably terse to the point of under-specification.

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

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

An output schema exists so return values need no explanation, but for an 8-required-parameter mutation tool with zero annotations and 0% schema coverage, the description omits too much to let an agent invoke it confidently.

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

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

Schema description coverage is 0% across 8 required parameters, so the description must compensate. It only gestures at three of them (revision, hash, environment) and leaves kind, outcome, summary, recorded_by, and work_item_id completely undefined, adding little semantic value.

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

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

The description uses a specific verb and resource ('Append evidence') scoped by revision, hash, and environment, so an agent can grasp the core operation. It does not, however, distinguish this tool from the sibling record_release_decision, which is a similar append-style recording operation.

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

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

There is no guidance on when to call this versus alternatives like record_release_decision or update_work_item, and no prerequisites or caveats are stated. The agent must infer the usage context entirely from the name.

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

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

With no annotations, the description carries the full burden. It does disclose one real behavioral trait beyond the schema: approval decisions are gated on QA evidence. However, it omits mutation semantics, what happens on an expected_revision mismatch, and whether the recorded attestation is immutable.

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

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

A single front-loaded sentence with no filler; the precondition clause is placed after the core action. It is efficient, though arguably too terse for a seven-parameter mutation tool.

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

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

For a 7-required-parameter mutation tool with zero schema coverage, no annotations, and an output schema, the description should at minimum explain the decision/revision semantics and the gate precondition's enforcement. It supplies only the gate hint, leaving the calling contract largely undocumented.

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?

Seven required parameters at 0% schema description coverage, and the description explains none of them. Terms like 'release-owner' and 'approval' only loosely gesture at decided_by and decision; work_item_id, expected_revision, environment, and required_kinds are entirely unaddressed.

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 ('Record') and resource ('caller-supplied release-owner attestation'), which is meaningfully distinct from siblings like record_evidence and evaluate_qa_gate. It stops short of explicitly routing between those siblings, but the resource is identifiable.

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 clause 'approval requires the QA evidence gate' implies a precondition for approval decisions, but the description never states when to call this versus evaluate_qa_gate or record_evidence, nor whether the gate must be run first. Usage is implied rather than directed.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully reveals that the operation creates a revision (implying history is preserved rather than destructive in-place mutation) and that source-hash binding is optional, but it says nothing about conflict behavior for expected_revision, permission requirements, or what happens to required fields omitted. That is a large gap for a five-required-parameter mutation.

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?

It is a single front-loaded sentence with no wasted wording. But brevity here is under-specification rather than economy — for a six-parameter mutating tool the one line is too sparse to be proportionate, though that is partly captured under contextual completeness.

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

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

An output schema exists, so return values need not be described. However, with no annotations, 0% schema description coverage, and five required parameters, the description leaves the agent without the information needed to fill the required fields or predict conflict handling. It is not remotely adequate for a tool of 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 0% across 6 parameters. The description explains only one of them, the optional source_hash, and even that only restates its binding target. work_item_id, expected_revision (presumably an optimistic-concurrency token), spec, status, and role are entirely undocumented in both the schema and the 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 does convey the underlying semantics — an update is implemented as a new revision — which is genuinely informative. However, the verb 'Create a new work revision' sits awkwardly against the tool name update_work_item and reads confusingly close to the sibling create_work_item, with no explicit statement of what distinguishes the two. An agent could plausibly route to the wrong tool.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_work_item or handoff_work. The only hint resembling guidance is that source_hash is optional, which is about a parameter rather than selection between tools.

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