feature-tracker-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation3/5
Most tools are carefully scoped and the descriptions do a lot of disambiguation work, but several pairs have blurry boundaries: parity_set vs parity_scan both write coverage, study_conclude vs study_status both touch the concluded state, and feature_ready vs feature_unblocked both answer what can be worked next. Agents would often need to read the full descriptions carefully to avoid misselection.
Naming Consistency4/5
The dominant pattern is domain-prefixed snake_case (feature_, gate_, goal_, study_, derive_, db_, confer_), which is predictable and consistent. Minor deviations like standup, checkpoint, tracker_status, and oz_shutdown do not fit the prefix pattern, but they are few and still readable.
Tool Count1/5
64 tools is an extreme surface for an agent to hold in context and choose among, especially when many are micro-operations like stash_restore, confer_digest, or goal_membership. Some consolidation into composite tools or subcommands would make the set far more usable without losing capability.
Completeness4/5
The lifecycle coverage is unusually thorough: features, goals, gates, studies, parity, workers, directives, derivations, backups, conferral, and shutdown workflows all have read/write/action counterparts. The main gap is the absence of a single-feature show/get tool for reading one tracked item's full detail, though feature_list likely covers basic lookup and agents can work around it.
Average 3.7/5 across 64 of 64 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- No commit activity data available
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It only adds that the output concerns 'how far each review has got'; it does not state whether the operation is read-only, how results are scoped or ordered, whether it can be expensive, or what failures are possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and contains no filler, but the brevity is under-specification, not effective structure. It is a fragment with no verb and no clear organization of 'what is listed' versus 'what progress information is returned'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must carry return semantics. 'Derivations and how far each review has got' is too vague to be actionable: the meaning of 'review', the role of the goal parameter, and the precise form of progress are all missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description needed to compensate for the undocumented goal parameter, but it does not. It neither explains how cwd or goal filter the result nor relates the term 'review' to either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the topic—derivations and review progress—so it is not a pure tautology. However, it is a noun phrase rather than a statement of action; it never says it lists or returns anything, and it does not distinguish derive_list from sibling derive_* tools such as derive_review or derive_features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit or implicit guidance about when to call this tool instead of alternatives. It does not mention a use case, exclusions, or prerequisites, and the large set of sibling derive_* tools makes the choice ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the operation is read-only and costs no work, which is useful safety and cost information. However, it does not describe what a decision entry looks like, whether results are paginated, what the default status is, or what happens when no decisions are awaiting a human, so behavioral transparency is only partially addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loads the core purpose and safety profile in two phrases. Every clause carries some signal: "Decisions awaiting a human" is purpose, "Read-only" is safety, "costs no work" is operational cost. While it is under-specified in other dimensions, it is not bloated or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema and no annotations, the description is too thin to be complete. It does not explain the status parameter's meaning or default, what fields each decision entry contains, or how this tool relates to gate_queue and other gate_* siblings. An agent could call it but would be guessing about the semantics of important inputs and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: the cwd parameter is documented in the schema, but the status parameter is only given an enum without explanation. The tool description does not compensate by explaining status semantics or defaults. An agent cannot confidently know whether omitting status returns pending decisions, all decisions, or something else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as decisions awaiting a human and marks the operation as read-only, so an agent can infer this is a list operation. However, it never explicitly states a verb like 'list' or 'show', and it does not distinguish itself from similar list-like siblings such as gate_queue or gate_list variants. The phrase 'Decisions awaiting a human' is helpful but does not fully clarify what the tool returns or how it relates to the other gate_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives like gate_queue, gate_reconcile, or gate_raise. The comment 'Read-only; costs no work' implies it is a safe, cheap operation, but it does not state when a user should choose gate_list over other decision-related tools. Without exclusions or alternative routing, an agent has limited basis for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It reveals that the tool shows provenance relationships, but says nothing about side effects, permissions, output format, pagination, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight, memorable sentence with no redundant filler. It is appropriately front-loaded, though it reads as a tagline rather than a complete definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a caller: it lacks any statement about how to identify the study, what the result looks like, and which sibling should be used instead. With no output schema and no annotations, the sole sentence is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: cwd is described but the required id property is not. The description only weakly implies that the id identifies the study; it adds no detail about either parameter or how they interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description communicates a specific resource scope: one study plus every feature it touched, framed as a provenance view. This makes it distinguishable from list-style siblings in intent, though it lacks an explicit verb like 'return' or 'display'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus close siblings like study_status, study_list, or feature_history. The description provides context but no exclusions or alternative selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does add one meaningful trait: results are deliberately small to avoid superficial review, and the page is limited to items still awaiting review. But it does not state whether the operation is read-only, whether it alters review state, how filtering works, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences and front-loads the core idea before offering rationale. The second sentence earns its place by explaining why small pages matter, though the poetic phrasing could be more operationally direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters, no output schema, and no annotations, so the description must carry significant explanatory weight. It leaves the meaning of required 'id', the role of 'cwd', the behavior of 'include_decided', and the output structure entirely unaddressed, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, so the description must compensate for the undocumented parameters. It does not explain the required 'id', the meaning of 'page', or the behavior of 'include_decided.' The 'deliberately small' comment loosely relates to per_page but adds little beyond the schema's stated default of 8.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys the resource—a small page of derivations still awaiting review—but does so as a noun phrase rather than a clear action like 'list' or 'fetch.' This makes the purpose inferable but not explicit, and it does not clearly distinguish derive_page from siblings such as derive_list or derive_features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'still awaiting review' and the warning about skimmed checklists imply this tool is meant for reviewing pending derivations in small chunks. However, there is no explicit when-to-use guidance, no exclusion of alternatives, and no mention of when derive_list or derive_review would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It mentions the conceptual output (waiting items and blockers) but does not disclose whether the tool is read-only, how it selects results, what response shape to expect, or any dependencies 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and avoids wasted words. The mirror framing is an efficient orientation, though the fragment style sacrifices clarity slightly; a slightly more explicit phrasing would make it ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description leaves significant gaps: return format, filtering behavior, required context, and relationship to related tools like feature_unblocked are not addressed. For a tool with two optional parameters in a large sibling set, this is not enough context for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes cwd, but the goal parameter has no description. The tool description adds nothing about either parameter and does not explain how goal or cwd influence the blocked list, so it fails to compensate for the 50% schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly communicates that this tool reports blocked work and the blocking dependency ('What is waiting, and on what'). 'The mirror of feature_ready' provides sibling differentiation, though it lacks an explicit verb like 'list' or 'get', so it stops just short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'mirror of feature_ready' implies this tool is the inverse of feature_ready and should be chosen when the ready-view is not what is needed. However, it does not explicitly state when to use this vs. alternatives like feature_unblocked or gate tools, so usage guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds useful context by noting the record is append-only and serves as the audit trail replacing git history, but it does not explicitly state that the tool is read-only or describe ordering, pagination, or side-effect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the first precisely listing the record's key fields and the second giving useful context about its role relative to git history. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential output content and the tool's audit-trail concept, which is helpful given no output schema. However, it leaves ambiguity around limit semantics, explicit read-only behavior, and selection among sibling history-like tools, so it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents id and cwd well, but limit is described only by its schema constraint; the description adds nothing about parameter meaning. At 67% schema coverage, the description should compensate for the undocumented limit parameter, and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the append-only record and enumerates its content: what changed, when, by whom, and against which git commit. This makes it clear that the tool exposes the audit trail, though it lacks an explicit verb like 'get' or 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use feature_history versus alternatives such as feature_list or the similarly named confer_history. The description only provides background context, leaving the agent to infer the appropriate use case from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly implies a mutating operation but discloses no side effects, reversibility, required permissions, or what happens if the dependency does not exist, leaving significant behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant wording. It is appropriately front-loaded and communicates the primary operation clearly without wasting the agent's attention.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no annotations, no output schema, and low schema description coverage, this description is insufficient. It omits parameter roles, dependency direction, behavioral effects, and any return or error semantics, leaving important context for the agent to fill in from the tool name and parameter names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only cwd has a schema description; id and depends_on are undocumented, and schema description coverage is only 33%. The description adds minimal parameter context by mentioning two features, but it does not clarify which parameter is the dependent feature or the dependency being removed, forcing reliance on parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Remove') and a specific resource ('a dependency between two features'), clearly conveying the tool's core function. It distinguishes the tool from siblings like feature_link, which presumably creates dependencies, based on the unlink/link verb contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusion cases. While removing a dependency is implied as the use case, there is no mention of feature_link or other related tools, leaving the agent to infer selection criteria on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It does communicate that only features lacking acceptance criteria are returned and frames them as refine work, but it never states whether the operation is read-only or if it has 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the core function in the first and a rhetorical context in the second. It's concise and front-loaded, though the second sentence is not strictly necessary for invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations or output schema and two undocumented parameters, the description leaves important details unstated: what the returned list looks like, how 'goal' filters, and how 'limit' behaves. It conveys purpose but is incomplete for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 1 of 3 parameters (cwd) has a schema description, and the tool description does not explain 'goal' or 'limit.' This leaves those parameters semantically opaque, and the prose adds no parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Open') and resource ('features with no acceptance criteria'), and adds the purpose as 'the work list for a refine pass.' This lets an agent distinguish it from general feature_list, though it doesn't explicitly name siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it—when preparing for a refine pass—by calling it 'the work list for a refine pass.' It does not explicitly name alternatives or conditions for not using it, so the guidance remains contextual rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states that the tool is a probe, reports coverage states, and explicitly says it is not the fix, implying non-mutating behavior. However, it does not clarify whether it requires a prior scan, how fresh the data is, or what 'cheap' means operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, with the core output stated first and the strategic purpose second. The phrasing 'cheap probe's target list' is somewhat cryptic but does not waste words. It earns high marks for brevity and front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a rough idea of the return value—counts per state—but leaves key context undefined: what dimensions are, how the `goal` parameter factors in, and how this tool relates to parity_scan or gap_scan. With no output schema and no annotations, these omissions make the tool hard to invoke with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with `cwd` documented but `goal` entirely undescribed. The description adds no parameter meaning and fails to clarify what `goal` represents in the context of coverage gaps. This is a notable gap for an agent trying to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool's output as coverage by dimension with counts of unknown, missing, partial, or satisfied features. It also frames it as a cheap probe's target list, which conveys its role as a diagnostic. However, it lacks an explicit verb and does not differentiate it from sibling tools like parity_scan or gap_scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is a cheap probe that decides where to spend effort and is not itself the fix. This gives a clear sense of when to consult it, but it does not explicitly mention alternatives, prerequisites, or when not to use it. The guidance is embedded rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It correctly implies a state-changing operation, but does not mention transition constraints, idempotency, what happens if a study is moved to the same status, or whether moves can skip statuses. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler and no redundancy. It front-loads the core action and lists the relevant statuses, making it easy to parse. It is concise without being falsely minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations, no output schema, and only partial parameter documentation, the description is incomplete. It omits important context such as the result of the operation, whether all transitions are allowed, and how errors like invalid status or missing study are handled. An agent would need to inspect sibling usages or infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description does not compensate for the undocumented 'id' parameter. The status parameter benefits slightly because the description repeats the enum values, but it adds no meaning beyond the schema. The description does not clarify what values are valid targets, what 'id' refers to, or how 'cwd' interacts with the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('move'), a resource ('study'), and the exact domain of statuses ('open, in_progress, concluded and abandoned'). This clearly distinguishes it from sibling study tools like study_open, study_conclude, and study_status, which only handle a subset of transitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as study_open, study_conclude, or other study-related tools. There are no prerequisites, no examples, and no exclusions, leaving the agent to infer that this is the general status-transition tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It does add useful behavioral context by stating that both positive and negative outcomes are reported and that this is deliberate for falsifiability. However, it does not disclose whether the tool is read-only, whether there are side effects, or what the returned digest concretely contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, and the second sentence usefully explains why both halves are reported. It is somewhat indirect and jargon-heavy, but it remains compact and every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only-looking digest, the description provides the gist and the reporting philosophy. However, with no output schema, it leaves the concrete return format, field names, and interpretation of 'could not settle' unspecified, and the domain-specific term 'peer channel' could confuse an agent without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, cwd, is fully documented in the schema with 100% coverage, so the description does not need to compensate. The description adds no parameter-specific meaning beyond the schema, which meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description communicates an evaluative purpose: reporting both where the peer channel changed the answer and where it could not settle something. This distinguishes it from raw event tools like confer_record or confer_history, though it lacks an explicit imperative verb and relies on the metaphorical phrase 'earning its place.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided, and no alternatives such as confer_history or confer_record are mentioned. The intended use case is only implied by the phrase 'whether the peer channel is earning its place,' so an agent must infer when to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose ordering ('newest first'), scoping behavior ('Omit both filters for the whole project'), and hints that the output contains settled arguments on record. However, it leaves the 'peer' relationship undefined and does not mention response shape, side effects, or any access considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler: result and ordering first, scope instruction second, practical warning third. It is appropriately concise and front-loaded, though the first sentence is slightly awkward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and three mostly undocumented parameters, the description is too thin. It never defines the subject/peer model, the expected value of subject_id, or limit behavior, leaving an agent to guess at critical calling details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%; only cwd has a description. The phrase 'Omit both filters for the whole project' adds useful semantics by implying subject_id and subject_kind are optional filters affecting scope. But it does not explain what subject_id refers to, how subject_kind constrains it, or what limit does, so the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'What a subject has been through with a peer' gestures at history retrieval but is vague: 'subject' and 'peer' are never defined, and there is no explicit verb like 'list' or 'return.' The 'newest first' ordering helps, but the description does not distinguish this from siblings like confer_digest or feature_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete when-to-use signal: 'Read this before re-litigating something' and clarifies that omitting both filters returns whole-project history. It provides clear context, though it does not mention alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It does add a meaningful behavioral clarification: parallelism is capped per goal rather than by token budget, and the limiting factor is simultaneous changes. However, it does not disclose effects like whether existing settings are overwritten, permission requirements, or reversibility, which would be useful for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary action is front-loaded, and the second sentence earns its place by clarifying a subtle point about parallelism. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation-like tool with no annotations and no output schema, so the description needs to convey more context. It explains the max_parallel concept but does not mention return behavior, error conditions, what happens to existing values, or any necessary prerequisites. For a tool with four parameters, including one undocumented name parameter, the description is not complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, so the description needs to add some meaning beyond the schema. It does clarify max_parallel by explaining the per-goal parallelism model, which is not in the schema. However, it does not add meaning for 'name' or cwd, and priority already has a schema description ('Lower is worked first'). The description helps but only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear operation ('Set') on a specific resource ('a goal's priority and how many of its features may be worked at once'). This is precise enough to separate it from goal_list, goal_show, goal_refine, and other goal-related siblings. It does not name an alternative, but the operation is distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to use this tool or when to prefer an alternative. The second sentence explains a semantic detail about parallelism rather than providing usage conditions, prerequisites, or exclusions. An agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It does disclose that backups are stored on disk and returned newest first, but it does not state whether the operation is side-effect-free, what a backup entry contains, or what happens when no backups exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only four words, all of which are meaningful, and the key ordering behavior is front-loaded. There is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one optional parameter and no output schema, this is minimally viable: it states where backups live and the sort order. However, without an output schema, it does not describe the shape of a backup entry or behavior on no backups, so an agent must infer the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the cwd parameter is already fully documented in the schema. The description adds no further parameter-level meaning beyond what is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('backups') and the key ordering behavior ('newest first'), and the plural name distinguishes it from the sibling db_backup. However, there is no explicit verb such as 'list' or 'retrieve', so the action is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance states when to call this over db_backup, db_restore, or stash_list. The description does not provide context, prerequisites, or alternatives; usage must be inferred from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose a key side effect ('unblocking the session'), but it does not mention whether the decision is reversible, what happens to the gate record, what permissions are required, or what the response contains. For a mutating tool this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one succinct sentence with no filler. The core action and consequence are front-loaded, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, no output schema, no annotations, and a broad sibling set, the description is too sparse. It does not explain the meaning of 'id', 'note', or 'cwd', nor does it describe return behavior or edge cases like non-pending gates. The sentence conveys intent but not enough to confidently invoke the tool in varied situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the description adds no parameter-level detail. It implies that 'id' identifies a pending gate and that 'decision' aligns with approve/reject, but the enum already covers that. The 'note' and 'cwd' parameters remain unexplained by both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Approve or reject') with a clear resource ('a pending gate') and states the consequence ('unblocking the session that raised it'). This clearly distinguishes it from siblings like gate_list, gate_raise, and even gate_decide_batch by focusing on a single pending gate decision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of use is implied: when a gate is pending and a session is blocked awaiting a decision. However, there is no explicit guidance about when not to use this tool or when to prefer alternatives such as gate_decide_batch, gate_reopen, or gate_reconcile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose one non-obvious behavior: results are ordered 'lowest priority number first'. However, it does not state whether the operation is read-only, what the default scope is, or what the response contains, so the behavioral disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences and front-loads the primary purpose and ordering behavior. Every phrase earns its place, though the 'tracked itens' wording introduces slight ambiguity without adding denity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema and no annotations, the description is minimally viable: it names the operation, sort order, and an important usage hook. But it omits filtering semantics, default behavior, return format, and any mention of sibling history/proposal tools, leaving material gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, with only cwd documented, and the description adds no parameter-specific guidance. The prose does not explain what goal, kind, limit, or status filter or control, so with low schema coverage the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core action with a verb and resource: 'List tracked items', and adds concrete behavior with 'lowest priority number first'. It is clear enough to distinguish from goal_list, gate_list, and study_list, though the resource 'tracked items' is somewhat generic and could be more explicit about the underlying feature/decision inventory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage context: 'Use before proposing, to avoid duplicates.' This clearly tells the agent when to invoke the tool, but it does not mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It discloses that reopened gates 'come back as hard' and frames the operation as a reversible lever, adding meaningful context beyond the schema. However, it does not state effects on related gates, whether reopening can fail, or what happens if the gate is already open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences and about 45 words, with the core action front-loaded in the first sentence. The middle sentence is somewhat philosophical but it earns its place by explaining why the operation exists; there is no filler beyond that.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter mutation, the description gives the key behavioral fact and rationale, while the schema covers cwd and note. It is incomplete on id semantics and postconditions, and without an output schema an agent gets no guidance on what a successful reopen returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 67%, and the required 'id' parameter lacks a description that tells the agent which gate it refers to. The prose adds no parameter-level detail; it never mentions id, cwd, or note. With coverage below the high threshold and no compensation in the description, a 2 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence, 'Pull back a gate the pair settled,' gives a specific verb and resource and clearly identifies this as the undo counterpart to gate settling. It is not tautological and it differentiates the tool from gate_raise/gate_decide. The phrase 'the pair settled' is somewhat jargon-heavy, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the intended situation: reopen when an auto-settled gate is later found wrong, because auto-settling is only safe due to reversibility. It stops short of naming alternative tools or stating when not to use it, but the use case is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a non-obvious behavior: imported features inherit goal membership from document headings, so membership reflects filing location rather than objective alignment. However, with no annotations provided, it does not explicitly state whether this is read-only or what the output shape will be.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and stays reasonably concise. The middle sentence supplies useful background about import-time inheritance, though it is slightly longer than necessary for the core instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides strong context about why membership may be stale and when to invoke the tool. However, with no output schema and sparse parameter details in the description, an agent still lacks complete guidance on what response to expect and how to format the goal identifier.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description does not compensate. It implies the 'name' parameter refers to a goal, but it does not clarify the expected format, how the goal is identified, or what 'cwd' contributes beyond the schema's existing description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's scope as everything filed under a goal, and explains its purpose is re-testing membership against an agreed objective. It distinguishes the concept from merely listing features by describing the filing-location origin, though it uses a noun phrase rather than an explicit verb like 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage instruction: 'Run this after refining a goal that already holds work.' This provides clear context for when the tool is appropriate, though it does not mention alternatives or explicitly say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains that the return includes relationship metadata (spawned, killed, informed) and frames the tool as a pre-flight check. However, it says nothing about read-only nature, pagination, filtering behavior, or return shape beyond those relation fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence plus an actionable advisory. Every phrase earns its place, though the opening 'Studies with...' is slightly elliptical and could be sharper as 'Lists studies with...'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, this description provides the essential mental model: a relationship-oriented listing used to avoid re-doing answered questions. It falls short on status semantics and return-value details, but the sibling context and enum values partly fill the gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain how the cwd or status parameters affect the result. cwd has a schema description, but status is only given as an enum with no semantic guidance. At 50% schema coverage, the description was expected to compensate for the undocumented status parameter but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (studies) and the key content (what each spawned, killed, or informed), making it clear this is a multi-study listing. It is distinguishable from siblings like study_show and study_status by implying a broader relationship-focused overview, though it lacks an explicit verb like 'List all'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Check before opening one' explicitly instructs the agent to consult this tool before study_open/study_show to avoid duplicated work. This gives a clear usage context, though it does not explicitly name alternative tools or state conditions when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It says 'Record' implying a write, and explains why recording killed matters, but it doesn't disclose whether repeated calls create duplicates, replace existing outcomes, require special permissions, have side effects on linked features, or what response to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded purpose. The second sentence earns its place by emphasizing the non-obvious importance of recording killed outcomes, so nothing is bloated or irrelevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write-style tool with no annotations and no output schema, important operational context is missing: idempotency, duplicate handling, whether a study can have multiple outcomes for the same feature, and what happens after recording. The rationale is well covered, but the invocation consequences are not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20%, but the description gives meaning to the central relation values (spawned, killed, informed) and establishes which identifiers are involved. It doesn't elaborate on note or cwd beyond schema, and the exact nuance of 'informed' remains vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and a clear resource relationship: a study spawning, killing, or informing a feature. It differentiates from generic study lifecycle tools like study_conclude or study_list by naming the outcome relation, though it doesn't explicitly contrast it with a sibling like feature_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when the tool is appropriate: whenever a study has spawned, killed, or informed a feature, and it explicitly stresses that killed outcomes must be recorded as much as spawned ones. It doesn't name exclusions or alternative tools for other link types, but the usage context is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the tool records a result and writes state, unlike parity_gaps, and it emphasizes that the probe is deliberately narrow and not a fix. It also clarifies the recording granularity: what was checked is recorded in each row's detail, which prevents mistaking absence of mention for absence of work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is front-loaded and useful, but the third and fourth sentences become philosophical and repetive, re-stating that the probe is narrow and records what checked. The description earns its place overall, but it could be tightened significantly without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description must provide context. It covers the main purpose, a key sibling contrast, and the recording behavior, but it does not state what the return value is, what 'the states' are exactly, or what side effects beyond recording occur. For a tool that appears to write parity state, this is a meaningful gap, though not severe enough to make invocation impossible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one of three parameters (cwd) has schema description, so coverage is low and the description needs to compensate. The description does add meaning to the dimension by saying probes exist for documentation and code and that other dimensions require real checks, which aligns with the dimension enum. However, neither the actor parameter nor the dimension parameter is explained explicitly in the description beyond that indirect reference, and cwd receives no description-level elaboration beyond its schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: run the cheap probe for one dimension across every feature and record the result. It also differentiates from parity_gaps, which is said to only read, making it clearer what parity_scan does that its sibling does not. The phrase 'makes the states real' is somewhat abstract, but the core function and scope are identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrast parity_scan with parity_gaps ('parity_gaps only reads; this is what makes the states real'), giving an agent a basis for choosing between them. It also explains that cheap probes are only appropriate for documentation and code, while other dimensions need a real check such as a build or applied migration, effectively stating when not to use this reference-search-like tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing mutation, overwrite semantics, idempotency, and side effects. It only says 'Record...' and does not state whether this updates existing values, whether the feature id must already exist, or whether history is written. This is too thin for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the action front-loaded and the reasoning attached succinctly attached. The second sentence earns its place by motivating why every dimension should be tracked rather than just code.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with six parameters, no annotations, and no output schema, this description is incomplete. id is undefined, state semantics are absent, and the relationship to feature_* and parity_* siblings is only implicit. An agent could guess the intent but cannot confidently invoke it correctly for all enum values and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description needs to explain id, state, dimension, and actor, but it does not. It lists some dimension values but omits 'screens' and 'features' from the enum and never explains the meaning of state values like 'missing', 'partial', or 'satisfied'. It adds domain context but not the parameter-level semantics an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and a clear resource: a feature's coverage in a single dimension, with examples. 'One dimension' helps set it apart from the query-oriented parity_gaps and parity_scan siblings. Minor omission of 'screens' and 'features' from the dimension list does not obscure the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives real usage guidance: record every dimension because work is only done when all dimensions are done, and warn against tracking only code. It does not explicitly name alternatives or exclusions, but the context for when to record each dimension is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool exposes an 'accumulated negative definition' built from refusals, and the imperative 'Read' implies a non-mutating operation. However, it does not state the output shape, whether any side effects occur, or prerequisites. It adds useful conceptual context but not full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the first states the core definition, the second elaborates on the source of boundaries, and the third gives a direct usage instruction. No fluff, front-loaded, and memorable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys purpose and when to use, but with no output schema and no parameter semantics for 'goal', it is not fully complete. An agent knows to read it before deriving/proposing, but not what the result will look like or how the 'goal' parameter affects the result. Given the simple optional-parameter surface, it is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%; the 'goal' parameter has no description in the schema, and the tool description does not compensate. The description does not mention 'cwd' or 'goal' at all, so an agent is left to infer what 'goal' filters or specifies. This is a significant gap given the half-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a resource about what the project is NOT — non-goals, refusals, and their reasoning. This distinguishes it from siblings like derive_features or feature_propose. However, it lacks an explicit verb like 'retrieve' or 'list'; 'Read before...' implies the action but does not name it directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Read before deriving or proposing anything' gives explicit context for when to use this tool — as a prerequisite for derivation or proposal workflows. It does not name alternatives or exclusions, but the instruction is clear enough for an agent to know this should be consulted early.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Record' and gives the rationale; it does not disclose whether the operation is idempotent, whether existing links are replaced, whether cycles are allowed, what gets changed, or what a successful response looks like. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is a clear, front-loaded definition. The second sentence adds motivational/usage context that helps an agent understand why the tool matters, though it is not strictly operational. Overall, it is concise and well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the schema, the description gives enough to identify required fields and the core action. However, with no annotations and no output schema, it omits important context such as return values, duplicate/cycle behavior, and the relationship to related tools like feature_unlink or feature_blocked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents id, depends_on, and cwd with helpful examples. The description reinforces the meaning of the dependency direction and the importance of the relationship, but it adds no new parameter syntax or semantics and leaves the 'note' parameter entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Record') on a specific resource ('one feature depends on another') and clearly communicates the directed dependency relationship. The rationale about blocked high-priority items also differentiates this from sibling status tools like feature_ready or feature_blocked.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: before relying on priority order, because dependencies can block the highest-priority item and waste a worker. It gives useful context but does not explicitly mention alternatives or exclusions, such as using feature_unlink to remove a dependency.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the result includes skipped_pending_a_gate alongside the ready list, explains why gates cause skipping, and warns that the worker must announce the skip. It does not explicitly state whether the tool is read-only, but the behavioral caveat is unusually rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit long but every part contributes: ready criteria, ordering, the skipped list, and the required verbal acknowledgment. Purpose is front-loaded and the behavioral caveat earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core concept, return contents, and an important behavioral expectation are covered, which is strong for a worker-facing tool. However, there is no output schema and no explanation of the goal and limit parameters, leaving material gaps for an agent that needs to invoke this tool with non-default arguments.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only cwd has a schema description, giving 33% coverage, and the description adds no parameter-level meaning at all. The goal and limit parameters are entirely unexplained in both the schema and the description, so an agent cannot infer how filtering or limiting works.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool does: it returns the work that can be worked right now, with explicit readiness criteria and ordering. It is distinguishable from sibling tools like feature_list or gate_queue because it centers on the worker's pull of currently actionable items, though it never explicitly says 'returns feature records' or names an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'This is what a worker pulls from,' which gives clear intended usage context for selecting next work. It explains the skipped-gate behavior and why that matters, but it does not name alternative tools or state when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses useful behavioral context: the tool surfaces staleness and feature counts, and explains why this matters. However, it does not specify staleness thresholds, output format, ordering, or side-effect status, though 'list' implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The essential output contents are front-loaded, and the second sentence adds a meaningful rationale for the tool's existence. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity list tool with one optional parameter and no output schema, the description communicates the key return values and the conceptual need for the tool. It is slightly light on staleness interpretation details, but the information is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, cwd, has 100% schema description coverage, so the baseline is 3. The description adds nothing about the parameter, but none is needed because the schema already documents its purpose and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (workers) and the information returned (staleness, time since last heartbeat, feature count). It lacks an explicit verb like 'list' or 'show', which keeps it from a 5, but the meaning is unambiguous and it is distinct from sibling worker_heartbeat by describing read-only status reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'An idle worker and a working one look identical without this' implies a use case: checking worker liveness/status. However, it does not explicitly state when to use worker_list versus alternatives such as worker_heartbeat, nor does it mention any exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly states the core side effect—the claim is given up and the feature returns to the pool—but it does not explain prerequisites, reversibility, error behavior, or effects on related data such as history or links.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It front-loads the action and outcome, and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, this one-liner is too thin for reliable autonomous invocation. An agent gets no detail about what id and worker mean, what success or failure looks like, or what exact post-conditions hold beyond the bare outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, covering only cwd. The description adds no direct explanation of the required id and worker parameters; it vaguely implies that id identifies the feature and worker identifies the claimant, but the required inputs remain largely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Give up a claim, returning the feature to the pool.' It clearly communicates the operation and distinguishes feature_release from sibling tools like feature_claim and feature_reassign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when a worker wants to surrender a claim and make the feature available again. It does not explicitly name alternatives or exclusion conditions, but the use case is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description has to carry behavioral weight, and it does convey queued, asynchronous behavior ('queued question rather than a message someone had to be present to catch') and a blocking wait. However, it overgeneralizes by implying every raise waits on a principal, while the schema says a converged conferral can close a soft gate without troubling the principal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the purpose statement front-loaded and a concrete example earning the second sentence. There is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (11 parameters, a nested conferral object, no output schema, no annotations), and the description alone leaves important operational detail implicit, such as the conferral requirement for soft gates. The schema compensates with rich field-level descriptions, so description plus schema is workable, but the high-level text is not fully complete on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 82%, so the schema already documents most parameters in detail; the description only adds semantic color to 'kind' by giving examples such as a $40 spend. That matches the baseline 3: the description does not need to re-list parameters but also does not materially deepen their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a concrete action ('raise') and a clear target: decisions the working session must not take alone, with four explicit trigger categories (architectural choice, install, spend, irreversible). It does not explicitly contrast itself with sibling gate tools such as gate_decide or gate_queue, so it stops 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit, actionable conditions for use: any architectural, install, spend, or irreversible decision, and it says the session should stop and wait. It does not spell out when not to raise (for example, after a converged conferral) or name an alternative tool, but the trigger context is clear rather than merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses that results are newest first, that each entry names its originating worktree, and that a stash only applies in the tree it was taken from. These are meaningful behavioral details beyond the name and schema. It does not mention output format or side effects, but the read-only nature is reasonably clear from 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary purpose and ordering are front-loaded, and the important worktree caveat is placed second. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the core purpose and an important behavioral constraint, but it leaves include_restored unexplained, and there is no output schema to clarify the return shape. For a simple listing tool this is close to adequate, but the missing parameter semantics prevent it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description does not compensate for the undocumented include_restored parameter. The cwd parameter is described in the schema and echoed by the worktree context phrase, but include_restored's meaning and effect are left entirely to inference. Since the description adds no parameter-level guidance beyond what the schema already says for one parameter, this is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as work interrupted by a shutdown and not yet restored, and specifies that results are ordered newest first. It strongly implies a list operation even though it does not begin with an explicit verb, and it distinguishes this from stash_restore by focusing on listing, not restoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context for when to use the tool: when you need to see shutdown-interrupted work that has not yet been restored. It does not explicitly name stash_restore as the alternative, but the 'not yet restored' framing and sibling tool list make the intended usage clear. No exclusion or conditional guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does communicate that this is a recording act and explains sequencing ('a worker cannot both review its own work and close it in one call, so the review has to exist first'). However, it does not disclose what happens on success, failure modes when the subject does not exist, or how the recorded conferral can be retrieved later.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The opening sentence states the core action, the second gives two concrete use cases, and the third gives the critical precondition. Every sentence earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no annotations and no output schema, the description covers the essential contextual grounding: what the tool records, when to use it, why the record must precede feature completion, and the existence precondition on the subject. It does not explain the return value, but absence of an output schema lowers that burden. The rich parameter schema covers the remaining invocation detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, and the schema already contains detailed descriptions for most parameters, especially inside the nested 'conferral' object. The description adds little parameter-level meaning beyond 'The subject must already exist,' which is a useful precondition for subject_id but not a semantic elaboration. The baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 an exchange with a peer model as its own act.' It clearly identifies the tool as a write/record action and gives concrete use cases (diff review before a feature is done, standalone conferrals). It does not explicitly name sibling tools like confer_history or confer_digest, so some sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Use for a diff review before a feature is marked done' and 'for any conferral worth keeping that is not attached to another write.' It also states a necessary precondition: 'The subject must already exist.' It stops short of naming alternative tools or explicit when-not-to-use cases beyond the 'not attached to another write' clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It explicitly discloses a meaningful behavioral trait: every change is appended to an append-only history stamped with the git commit it was made against. This gives the agent valuable expectations about auditability and mutability beyond the bare 'change' verb, though it does not cover permissions or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action and scope are front-loaded, and the audit-history behavior is appended concisely. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 annotations and no output schema, the description is too terse. It does not explain partial-update semantics, the intended use of actor/acceptance/note, or what the caller should expect back after invoking the tool. The schema helps, but the combination of high parameter count and lack of output schema leaves significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 44%, so the description needs to compensate for the undocumented parameters. It does add value by naming title, body, and priority as changeable fields, which the schema leaves somewhat opaque. However, it does not clarify the purpose of actor, acceptance, note, or how omitted fields behave during a partial update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Change a tracked item' and enumerates the mutable fields: status, title, body, or priority. This clearly distinguishes the tool from siblings such as feature_propose, feature_list, and feature_history, which are about creating, listing, or inspecting items rather than modifying them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'tracked item' implies this is for modifying an existing item rather than proposing or listing one, but no explicit when-to-use, when-not-to-use, or alternative tool is named. It does not mention, for example, that feature_propose is the right choice for new items or feature_reassign for reassignment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It conveys that the tool returns category metadata and is meant for inspection before proposing, but it does not explicitly state it is read-only, how cwd affects results, or how the list is ordered/grouped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each with a clear role: content, domain importance, and actionable usage. There is no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one optional parameter and no output schema, the description covers the returned attributes and the reason to call it. It could be slightly more explicit that the tool is read-only and returns a list, but nothing essential is missing for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, cwd, is already fully documented in the schema, so schema coverage is 100%. The description adds no parameter-specific detail, matching the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (categories/goals) and the returned attributes (priority, parallelism cap, item counts), and implies a listing action. It is distinguishable from feature_list and goal_show because it emphasizes categories and the pre-proposal check, though it never explicitly states a verb like 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete usage instruction: check this tool before proposing a feature so near-duplicate goals are not created. This is clear context, but it does not name alternative tools or state explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses exactly what the operation returns and frames the tool as a read action by saying the worker 'should read this', implying no side effects. It does not discuss errors or auth, but for a simple show operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler. The first sentence front-loads the output content; the second provides the usage directive. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-goal retrieval tool, this description covers the return content and the when-to-use guidance, and the schema covers cwd. It does not explain not-found behavior or output format, but those are minor gaps given the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: the cwd parameter is documented but the required name parameter is not. The description never mentions either parameter, so it does not compensate for the gap. The agent must infer that 'name' selects the goal to show.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool returns: one full goal with objective, definition of done, exclusions, constraints, and item counts. It lacks an explicit verb like 'retrieve' or 'display', but the phrase 'One goal in full' plus the tool name make the purpose clear and distinguish it from a goal list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the worker when to call this tool: before starting work, so it can verify that what it builds serves the goal. It does not mention alternative tools or when not to use it, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly states that progress is never a ratio and explains why a percentage would misreport regression. It also discloses provenance by saying which database and tree were read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core counts, and the second sentence earns its place by preventing a common misinterpretation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status tool with no annotations and no output schema, the description explains the return content and a key interpretation trap. It could add explicit read-only/ side-effect phrasing, but 'which database and tree were read' strongly implies a non-mutating status read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single cwd parameter is already fully documented. The description adds no additional parameter-level meaning, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb 'Counts' and the exact resources counted: status, goal, pending gates, and database/tree provenance. This clearly distinguishes it from sibling list and mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use tracker_status versus siblings like feature_list, gate_list, or study_status. The purpose implies an overview/status role, but no explicit when-to-use or alternative routing is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it goes well beyond the schema by explaining that 'wrong_goal' is a routing error that moves the feature rather than dropping it, while 'not_wanted' is a project-level decision. It also communicates why rejection rationales are mandatory. Minor gap: it only discusses two of the five rejection reasons, leaving duplicate/unclear/superseded behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with the core verb and resource front-loaded in the first clause. Every sentence earns its place: purpose, rejection semantics, and the rationale policy are all relevant and tightly written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough for the main invocation path: agent knows what actions are available, what the two critical rejection meanings are, and why rationale is mandatory. The main gap is that duplicate/unclear/superseded are not described, but the schema enum supplies those values and the tool's most dangerous ambiguity is already resolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds genuine semantic value to the central 'decisions' parameter: it explains what 'accepted' effectively does, what rejection means in each key case, and why 'rationale' is required. It does not document cwd/actor, but those are largely self-expianatory from schema/names, and the core parameter is substantially clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Review backlogged features' with concrete outcome categories: promote to 'agreed', reassign, or drop. The operation is clear, though it does not explicitly differentiate itself from sibling tools like feature_update, so some inference is still required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by 'Review backlogged features', which is enough to suggest when to call it, but there is no explicit when-not or alternative routing guidance. An agent cannot easily rule out overlaps with feature_update or feature_reassign from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the sole source of behavioral information. It discloses the main effect (the directive will no longer be returned to this worker) but does not mention side effects, reversibility, or whether the directive is deleted or globally acknowledged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise, front-loaded sentence with no redundant words. It states the action and the outcome efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, but the lack of annotations, output schema, and parameter descriptions means the description carries a heavier burden. It covers the core purpose but leaves parameter semantics and behavioral details to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 33% description coverage, with only cwd described. The phrase 'this worker' gives some meaning to the worker parameter and 'acknowledge a directive' implies id refers to the directive, but id and worker remain largely undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Acknowledge') and resource ('a directive') and adds a clear outcome ('so it stops being returned to this worker'). It is distinct from sibling tools like directive_issue and directive_poll, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: the tool is used when a worker wants to stop a directive from being returned. Although it does not explicitly name alternatives or exclusions, the condition is easy to infer from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the lease-vs-flag model, expiry, and the consequence of not claiming. It stops short of stating failure behavior if the feature is already held or the lease duration default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose and then adding the lease model and a practical warning. The lease explanation is a bit elaborate, but it earns its place because it is central to the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a strong behavioral model for the claim action, which is enough to make a basic call with id and worker. However, it omits useful call context like the lease_minutes default, what happens on a conflicted claim, and what the return response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description never mentions id, worker, cwd, or lease_minutes. Schema coverage is only 50% (id and lease_minutes lack descriptions), so the description should compensate for parameter meaning but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Take a feature to work on, if nobody else holds it.' This clearly identifies a claim operation and distinguishes it from siblings like feature_propose, feature_list, and feature_release.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: claim before starting work, and only if nobody else holds the feature. It does not explicitly name alternatives or say when not to use it, so it falls just 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it does disclose the batch nature and the derivability heuristic. However, it does not say whether existing acceptance criteria are overwritten, whether a conferral is required for execution, or what happens in error or return cases, leaving important behavioral context undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly three sentences with no fluff: the action, the rationale, and the routing rule. The most important information is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex batch mutation tool with a required nested conferral object and no output schema. The description provides a clear decision framework but omits side effects, overwrite semantics, and return behavior; the schema supplies the conferral contract, but the description alone is not fully sufficient 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers cwd and conferral well but leaves actor and items thin, with only 50% coverage overall. The description adds useful meaning for items by explaining that acceptance criteria are derivable from body/code/docs and that undecidable cases should become gates, but it does not explain actor or the non-acceptance item fields, so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific action (Set acceptance criteria) on a specific resource (many features at once), so the purpose is immediately clear. It contrasts with one-at-a-time work, but it does not explicitly name a sibling tool such as feature_update, so it does not quite reach the top distinction score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit positive condition for use: acceptance criteria are mostly derivable from the body, code, and docs, so batch work avoids needless round trips. It also gives an explicit negative rule: anything genuinely undecidable should become a gate rather than a guess, which routes the agent away from this tool when a decision cannot be derived.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the dry-run default, the protected status of goals with work, and that Miscellaneous is always kept. This meaningfully informs the agent about side effects and safety guardrails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the primary action, and the second adds the essential safety conditions. There is no fluff or repetition, and the most important behavioral information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two optional parameters and no required inputs, the description covers the core behavior and safety constraints well. It does not specify the exact output format, but since there is no output schema and the action says 'List categories,' this is a minor gap rather than a functional one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already documented. The description adds important semantics around the apply parameter: omitting it results in a dry run, and even when applying, certain goals are never removed. This goes beyond the schema's 'Omit for a dry run.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: list categories with no features and optionally remove them, which clearly distinguishes it from goal_list or feature_list. The term 'categories' is slightly ambiguous but is clarified by 'goal with work' in the next sentence, meaning goal categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: identifying empty goal categories and optionally removing them. However, it does not explicitly state when not to use it or point to alternatives like goal_list or goal_show for inspecting goals in more detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the behavioral burden. It discloses filtering criteria, ordering by work held, and the row-level doc_ref behavior. It implies a read-only report but does not explicitly state side-effect absence or pagination limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all contributing either selection criteria, rationale, or workflow guidance. The first sentence front-loads the core purpose. Slightly wordy, but each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains that rows carry doc_ref where known, which is enough to support the refine workflow. It does not enumerate all return fields, but for a simple filtered list tool with one optional parameter, the coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, cwd, is fully documented in the schema with 100% coverage. The description does not add anything about how cwd affects the result, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a listing of goals lacking an objective or definition of done, ordered by carried work. It is distinct from generic goal_list and goal_show tools, but it does not use an explicit verb like 'list' or 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable guidance: refine the goals holding the most work first, and use the doc_ref to avoid searching the tracker. It implies a workflow but does not explicitly name the refine tool or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses key side effects: records are placed in the backlog at 'proposed', not agreed, and candidates that match existing features are reported rather than created. It also exposes the prerequisite of calling project_boundaries first, which is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: the core action is stated first, followed by the status implication, the rationale, and the required ordering with project_boundaries. Each sentence contributes either purpose, workflow, or behavior, with no wasted filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's role, side effects, deduplication behavior, and a prerequisite call, which is strong for a mutation tool with no annotations. However, it does not describe the return/value produced after invocation, and it leaves several parameters under-explained despite low schema coverage. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate for undocumented parameters. It mentions 'goal' and 'candidates' semantically and explains matching behavior, but it does not explain parameter meanings, how candidates should be structured, or what 'source' and 'cwd' contribute. The description adds little beyond the property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Derive a feature checklist for a goal from the documentation and existing features' and clarifies the exact disposition 'put it straight in the backlog at proposed'. It also distinguishes itself by explaining that matching candidates are 'reported rather than created', so an agent can separate it from feature_propose and similar siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear workflow context: call project_boundaries FIRST to avoid re-proposing refused work, and it frames derivation as a required output of goal definition ('Defining a goal must produce work'). However, it does not explicitly name when-not-to-use it or contrast it with alternative derive_* or feature_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals key non-obvious behavior: directives are broadcast, persistent enough that late-starting workers still see them, and can be scoped. This goes beyond the schema. It does not cover all side effects of each directive kind, but the core behavioral trait is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action and target appear in the first sentence, and the crucial broadcast/late-start distinction follows immediately. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the central broadcast concept and scoping behavior, which are the most important non-obvious aspects. However, with no annotations, no output schema, and undocumented note/actor parameters, some operational context is missing. It is adequate but leaves room for more detail about what each directive kind actually does and how workers consume it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description only elaborates on 'scope'. It also names the kind values, but those are already visible in the schema enum. Parameters like 'note' and 'actor' receive no explanation in either the schema or the description, leaving significant semantic gaps that the description should compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Broadcast') and a specific resource ('stop, pause, resume or rescan to every worker'). It differentiates this tool from point-to-point/addressed messaging and from siblings like directive_poll and directive_ack by emphasizing the broadcast and late-start visibility semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use this tool: whenever a directive must reach all workers, including those that start later. It contrasts this with point-to-point messaging and gives the scoping rule ('Scope it to a goal, or omit for all'), which is explicit usage guidance. It does not explicitly name alternative tools, but the broadcast-vs-addressed distinction provides clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and it does good work: it reveals that the tool returns unacknowledged directives and defines the stop and pause semantics. It doesn't cover edge cases like no pending directives or how resume is triggered, but the main runtime contract is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The key instruction ('poll between units of work') is front-loaded, and the response semantics are packed into a compact second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough context for the polling semantics but leaves the goal parameter unexplained and does not state what happens when there are no directives, nor how a worker is identified. For a simple read-oriented tool this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; only cwd is documented. The description mentions 'this worker' but never explains the required worker parameter or what goal means, and it doesn't add parameter-level meaning to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource, 'directives this worker has not acknowledged', and gives a clear operational verb, 'Poll between units of work'. It also distinguishes this tool from directive_issue/directive_ack by focusing on unacknowledged directives rather than creating or acknowledging them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: poll between units of work, and instructions to obey the returned directive. It does not mention when not to poll or name alternatives, so it misses the full when/when-not contrast, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does meaningful work: it explains that answering a gate only changes the gate row, leaving held work invisible until looked at, and that this tool is that lookup. It also discloses that decision_note contains the awaited answer. It does not explicitly state whether the tool is read-only or describe output shape, but the 'nothing else' phrasing implies the operation is observational.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the purpose, the underlying gate-behavior context, and the operational instruction to read decision_note. It is front-loaded with the core idea and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter query tool with full schema coverage, the description is largely complete: it explains when to call it and what the returned data means. It could be more explicit about the exact output format and read-only nature, especially since there is no output schema and no annotations, but the description is still sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 cwd and since_hours. The description adds no parameter-specific meaning, which is acceptable under the baseline for high-coverage schemas but gains no extra credit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that the tool reveals work released by a recently answered gate, using 'released' as the key verb and 'work' as the resource. It is clear enough for an agent to understand the tool's function, but it does not explicitly name or contrast a sibling like feature_blocked, leaving some differentiation implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is what a worker calls on resuming after a gate has been answered, and it instructs reading each decision_note before starting. It does not explicitly state when not to use it or name alternatives, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden, and it delivers: it states the tool will read the source document once, slice it by heading, draft all goals, record doc_refs for future passes, and raise unresolved questions as gates. This goes well beyond a generic 'refine' and discloses real side effects and workflow traits. It does not cover reversibility or return values, but for a drafting/refinement tool this is substantive disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. The middle sentence about the 'expensive part' and 'not a sitting per goal' is somewhat rhetorical but still earns its place by justifying the batching pattern. Overall, every sentence adds either instruction or context without excessive bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema descriptions, especially for conferral, are rich and fill many gaps. However, the top-level schema marks only goals as required while the conferral description insists it is required—an internal inconsistency the agent must resolve. The main description also leaves the source document unparameterized, and there is no output schema, so return behavior is completely unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with actor having no description at all. The main description adds useful semantics for doc_ref—'a pointer instead of a search'—and for the batch behavior of the goals array. However, it does not clarify cwd, actor, or how the 'source document' mentioned in the description maps to any actual parameter, leaving some semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Refine several goals in one call' is a specific verb+resource statement, and it clearly distinguishes this from the sibling goal_refine by emphasizing the batch nature. The rest of the description reinforces the purpose by outlining the workflow: read once, slice by heading, draft all, record doc_refs, and raise remaining questions as gates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool—when several goals need refinement and the source document can be read once—and it explains the efficiency rationale. It does not explicitly name goal_refine as the single-goal alternative or list exclusions, but the batching guidance is strong enough to route an agent appropriately. The conferral parameter description adds the key guideline of one peer call per batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It usefully discloses that negative and abandoned outcomes are valid, successful conclusions, and that linking must happen first. However, it does not explicitly state that this tool finalizes or changes the study's status, nor does it describe any side effects or whether the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the core purpose, the critical semantic nuance about successful conclusions, and the required upstream workflow. Information is front-loaded and there is no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description covers the key conceptual traps an agent could get wrong: negative outcomes count as success, abandoned is valid, and feature links must be recorded beforehand. It does not detail every parameter or consequence, but it gives enough context for correct invocation in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the description must compensate. It adds useful meaning to recommendation, document_path, and status by framing them around conclusions and abandoned outcomes. However, the required id parameter is not explained, and actor is left undocumented, so the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Record a study's recommendation and the document it produced.' It also clarifies the scope of a successful conclusion, including negative outcomes like 'Do not build this' and 'abandoned.' This clearly differentiates it from sibling tools like study_open, study_show, and study_outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance: use study_conclude to record the recommendation and document, and explicitly instructs the agent to link spawned/killed features with study_outcome before concluding. It does not explicitly state when not to use the tool or name alternatives beyond study_outcome, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and it does real work: it states the side effect (lease extension) and the failure mode (silence to claims expire to work picked up). It stops short of detailing idempotency or what a successful response looks like, but the core runtime semantics are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a distinct job: action, consequence, and cadence. The most decision-relevant information is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures why and when to heartbeat and the consequence of silence, which is the minimum viable context. It is incomplete for a 5-parameter/no-output-schema tool because it never explains the optional parameters, the required worker value, or the response/error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20% (only cwd has a schema description), and the tool description compensates for almost none of that. It adds only the general idea that `worker` identifies the living worker; `goal`, `worktree`, and `session_id` remain unexplained and ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Report that a worker is alive and extend its leases') and names the resource and effect. The stale-silence explanation differentiates it from one-shot status/list tools like worker_list and checkpoint, so an agent can identify its purpose without reading schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call this every few minutes while working' is a direct, explicit trigger condition. It does not name alternative tools or give a when-not-to-call exclusion, but it clearly scopes use to active work sessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses atomicity (single transaction, leaving no half-captured design) and duplicate handling (reported, not skipped or forced), both important call-time behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence front-loads the action and scope; the subsequent sentences add meaningful behavioral and rationale content. Slightly wordy, but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested objects and no output schema, the description adequately explains the overall contract and failure behavior. However, it never mentions the required conferral sub-object, leaving an agent to discover it solely through the schema; the schema is rich enough to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (83%), including rich descriptions for items and conferral, so the description does not need to restate parameters. The only gap is that it doesn't clarify the undocumented actor field, but baseline 3 applies when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (record) and exact scope (everything agreed in one design session) and frames it as a single transaction. It distinguishes itself from per-item sibling tools by explaining that design artifacts only make sense together.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the when: at the end of a design session, all agreements should be recorded atomically. It implies the alternative of recording one item at a time is wrong, but it does not explicitly name or exclude sibling tools like feature_propose or confer_record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does disclose a key side effect: calling this tool records that each gate was put to the principal. It also reveals ordering and the design intent to batch decisions into one sitting, though it leaves details like error behavior and repeated-call effects unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core behavior before adding context. The aphorism 'a gate that only asks is a gate that gets deferred' adds flavor and rationale, but it is the least directly actionable sentence, keeping this from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description compensates for the lack of an output schema by specifying what each queue item carries and noting the audit side effect. It does not mention pagination or parameter-specific behaviors, but both parameters are already well documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters completely, so the description does not need to carry much parameter burden. It adds no extra meaning for cwd or goal beyond what the schema provides, matching the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a queue of every pending decision, ordered oldest first, and specifies the fields it carries: age, what each gate blocks, options, and the raiser's recommendation. It distinguishes itself from siblings by tying it to the periodic question round and the recording of gates being put to the principal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case—'Use this for the periodic question round'—and explains the recording behavior. It does not name alternative tools or state when not to use it, but the intended context is clear enough for an agent to select it over a general list or decision tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It meaningfully discloses that this tool reads working trees, not just commit history, and explains why that matters with a concrete warning about worktree divergence. It does not mention absence of side effects or performance considerations, but nothing in the description suggests mutation and the read-only tone is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and efficiently front-loads the core value proposition. The second sentence uses an anecdote to justify the working-tree read behavior, which is useful albeit slightly verbose; it still earns its place by alerting the agent to a subtle correctness pitfall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one optional, schema-documented parameter, and the description enumerates the key output dimensions even though no output schema exists. It doesn't detail return formatting or exact field names, but for a cross-track status snapshot the described scope is sufficient for a capable agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single 'cwd' parameter is already well documented in the schema. The tool description does not add parameter-level detail, but because the schema fully covers it, the baseline rating of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete deliverable: cross-track state in one call, and enumerates exactly what it surfaces: counts, blocked items, pending gates, worker liveness, and uncommitted worktree changes. It clearly differentiates from sibling tools like feature_list, gate_list, and worker_list by being an aggregate cross-track snapshot rather than a single-track listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes clear usage context: use this when you want cross-track state in a single call. It does not explicitly name alternatives or exclusion conditions, but the description's emphasis on reading working trees and covering multiple tracks gives an agent enough context to choose it over narrower sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully explains conceptual behavior: the deliverable is a document and decision, not code; there are no acceptance criteria; it may conclude 'do not build this'. However, it does not state side effects such as whether a study record is created, what state it enters, what the call returns, or any follow-up needed. This is a noticeable gap for a creation action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: purpose first, then usage conditions, then an explicit exclusion. Every sentence earns its place, and there is no redundant filler or restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema and no annotations, the description should explain return behavior and effects, but it does not. It gives strong conceptual framing and usage context, yet omits operational details like what a successful open returns and how it connects to study_design/study_status. For a creation command, that leaves an agent with some uncertainty about what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, covering cwd, context, and question, while actor is undescribed. The description adds no per-parameter detail, though it does reinforce that 'question' must be genuinely answerable through analysis. It does not compensate for the undocumented actor parameter or provide syntax or format guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Open an investigation', and immediately defines the deliverable as 'a document and a decision, not code'. It explicitly contrasts with feature work, which helps differentiate it from feature_propose and other build-oriented siblings. Among the study_* tools, 'open' clearly signals the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when a question needs real analysis before anything can sensibly be built' and gives concrete examples of such questions. It also provides an exclusion: 'A study is NOT a feature' with criteria that distinguish when this tool is inappropriate. This effectively routes the agent away from feature tools without needing to open their schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the dump is written to .oz/backups, is portable ('restores anywhere'), and crucially is verified before being reported — 'an unverified backup is a file, not a backup.' It does not cover failure modes or permissions, but the core safety behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the action, the timing, and the verification/portability principle. The core command is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple backup tool with optional params and no output schema, the description covers what it does, where it writes, when to use it, and how success is determined. It could be more explicit about return values or error behavior, but an agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 cwd and label. The description adds contextual color about when backups are appropriate, but does not add parameter-specific semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Dump the project's tracker to .oz/backups and verify it.' This clearly identifies the operation, its target, and the verification step, and the action is distinct from reading or listing backups (db_backups) or restoring them (db_restore).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit timing guidance: 'Take one before any bulk change — a refine pass, a restore, a migration.' It also contrasts with copying the data directory, but it does not name or explicitly exclude sibling tools such as db_restore or db_backups, so the alternatives guidance is only partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it does so strongly. It warns that feature gaps become 'proposed' backlog items, that goal gaps become HARD gates that gate_reopen cannot unwind once work routes in, and that a settled refusal from gap_scan is a decision rather than an oversight. These are exactly the consequential side-effects an agent needs to know before invoking a recording tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient; nearly every sentence carries behavioral or sequencing value. It front-loads the core purpose with 'Record what a gap analysis found.' It is arguably a single dense paragraph rather than structured guidance, but given the complexity of the tool, the length is justified and there is little waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's most important caveats, but it does not specify how to represent a legitimate 'nothing found' outcome in the schema (empty arrays? a single call?), nor does it explain the returned result since there is no output schema. The schema provides strong parameter-level documentation, so this is not a fatal gap, but a complex tool with no output schema should give a bit more operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%, and the schema already documents most parameters richly. The description adds high-level meaning about why goal_gaps are consequential and how feature_gaps flow downstream, but it does not compensate for the undocumented parameters or clarify how to encode the 'finding nothing' outcome in terms of specific parameter values. This is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 what a gap analysis found.' It then distinguishes the two artifact types (feature gaps vs goal gaps) and explicitly ties feature gaps to downstream sibling tools (derive_page/derive_review), so an agent can tell which output this tool produces and how it relates to nearby tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit sequencing guidance: 'Call gap_scan first and check every candidate against the refusals it returns.' It also sets a clear policy for when recording nothing is appropriate, which is a form of when-to-use guidance. However, it does not explicitly name an alternative tool to use instead of derive_gaps in any situation, so the 'vs alternatives' dimension is only partially addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It adds meaningful non-obvious behavior: 'The goal is created if it does not exist' and 'the id is allocated atomically... so concurrent sessions cannot collide.' This reveals side effects and concurrency guarantees beyond a simple 'create' statement. It does not mention return format or error conditions, but the atomic/allocation and goal-creation traits are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no wasted words. The core purpose is front-loaded, followed by the key concurrency/creation behavior and then a crisp usage guardrail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given eight parameters, two required, no output schema, and a large sibling family, the description covers purpose, when-not-to-use, goal-creation side effect, and atomic id allocation. The only notable gap is that a successful propose's return value is not described, which matters more because there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 eight parameters. The description adds context around goal auto-creation and id allocation, which relates to 'goal', but it does not add per-parameter meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Record a feature, guardrail, schema change, risk or mitigation', so the agent immediately knows this is a create/insert operation. It further distinguishes itself from read/tracking siblings by instructing 'check feature_list first' and by framing itself as a persistence operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit inclusion criteria ('what would otherwise be lost, is actionable') and an explicit exclusion ('is not already tracked -- check feature_list first'). The main gap is that it does not name a modifier sibling like feature_update as the option for already-tracked items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it discloses non-atomicity ("Each decision applies independently"), per-item reporting ("is reported separately"), and partial-failure acceptance ("nine of eleven is a normal outcome, one bad id must not throw away eight good answers"). This is exactly the behavioral trait an agent cannot guess from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with the purpose front-loaded and zero redundancy with the schema: one sentence for what the tool does, two for the critical behavioral semantics. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex batch tool with no output schema and no annotations, the description covers the when, the what, and the failure semantics that matter most for safe invocation. The main residual gap is the return shape — "reported separately" hints at per-decision results but no response format is given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: cwd and note are already well documented in the schema, while answers, id, and decision are not. The description compensates partially by explaining that answers are processed independently and that a bad id is tolerated, but it never defines what an id refers to in the question-round context — that gap is left to inference from sibling tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Answer several gates at once" states a specific verb, resource, and scope, making the batch behavior unmistakable. The framing differentiates it from the singular sibling gate_decide without needing to open either schema, and "after a question round" anchors it 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage context — batch decisions after a question round — but never explicitly contrasts it with gate_decide for single gates or states exclusions. An agent must infer the single-vs-batch routing from the tool name and sibling list rather than from explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It implies a persistent write that should occur exactly once and explains the state it addresses, but it does not state whether an existing objective is overwritten, whether the goal must already exist, or what response the agent should expect. Those gaps keep it below a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three purposeful sentences: one for the action, one for the rationale, and one for the timing rule. It is front-loaded with the core directive and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no annotations and no output schema, the description plus the rich parameter schema is mostly sufficient. An agent understands what to do, when to do it, and what the core fields mean. It falls just short of fully complete because required-name semantics, overwrite behavior, and return behavior remain implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 73%, and most parameters already carry detailed descriptions in the schema itself. The narrative adds conceptual value about objective versus name/priority, but it does not clarify undocumented parameters such as `name` and `actor`, nor does it compensate for all gaps across the 11-parameter surface.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific action and resource: record a goal's objective after a refinement session. The filing-label explanation further clarifies why this is needed and distinguishes it from merely listing or naming goals, so an agent can recognize the intended operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear trigger ('after a refinement session with the principal') and a clear prohibition ('Do NOT call this mid-discussion — record once, when consensus is reached'). It directly addresses the timing risk for this tool, which is strong practical routing even without naming a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and explains that results are returned unsummarised on purpose, with the rationale that gaps are noticed by reading actual wording and do not survive condensation into counts. It does not mention volume, size, pagination, or output envelope behavior, but the disclosed traits are meaningful and beyond trivial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than a one-liner but every clause earns its place: it defines content, declares read-only behavior, differentiates from a sibling, and justifies unsummarised output. The core content is front-loaded with 'Everything needed to reason about coverage, in one read,' and the rest supports selection and expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does a good job explaining what will be returned and why, which covers the most important contextual gap. It also gives usage context through the derive_features contrast. It could more explicitly mention response shape or size expectations, but for a read-only scan tool the definition is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter cwd is already fully documented in the input schema with 100% schema description coverage, so the description does not need to repeat it. The description adds no further parameter-level guidance, which is acceptable given the schema already handles the meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it returns a full, unsummarised read of all goals' objectives, done-means, non-goals, constraints, holdings, and refusals for coverage reasoning. It also explicitly distinguishes itself from derive_features by contrasting whole-set coverage analysis with single-goal implication. This gives a precise verb-resource-scope identity, not just a restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool vs derive_features: use gap_scan to analyze what the whole set fails to cover and find MISSING goals, whereas derive_features can only find work inside goals someone already wrote. This is a clear when/alternative pairing, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: it explains the pre-registration rationale, that revisions are later allowed and counted, and that a silently revised method is indistinguishable from a fitted one. These are meaningful behavioral facts beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, each earning its place, with the action and timing front-loaded and the rationale and constraints following. Nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema richly documents the nested conferral object and method, but the description never explains what 'id' refers to, whether this call creates or updates a record, or how a later revision is technically performed. The schema's 'Required' note on conferral also conflicts with the top-level required list, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71% and the schema's own parameter descriptions are detailed, so the baseline of 3 applies. The free-text description adds no parameter-level meaning beyond referring to the method, but the schema compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Record the method agreed with the principal, BEFORE execution.' It clearly frames this as the pre-registration step in the design phase and distinguishes it from execution and outcome tools by naming the artifact and timing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this once, at consensus' and 'do not execute a study that has no method recorded,' giving clear when and when-not guidance. It does not name alternative tools, but the context is strong enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral burden. It discloses two non-obvious traits: the id remains stable so external citations still resolve, and the move is recorded in history with its reason. It does not cover permissions or reversibility, but for a move operation the disclosed context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste: the action is front-loaded, followed by the two behavioral guarantees, then the usage trigger. Every sentence earns its place and the description is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers what the move does, why the id matters, how history records it, and when to use it. It does not describe the return value or side effects on old/new goals, but those are largely implied by 'move' and are not required by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers cwd, goal, and note, but leaves id and actor bare. The description adds semantics to id ('never changes') and to note ('recorded in history with its reason'), partially compensating for the 60% schema coverage. It does not explain actor, but that is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Move a feature to a different goal.' This clearly distinguishes it from siblings such as feature_propose, feature_update, feature_link, and feature_unlink by naming the intended mutation and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete trigger: 'Use when a refined objective shows an item does not belong where it was filed.' It does not explicitly name exclusions or alternatives, but the stated condition is enough to route an agent to this tool rather than generic update or link actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it does so excellently. It explains that the stash is applied rather than dropped, that conflicts can be retried or abandoned without losing work, and that dirty worktrees are rejected with a clear rationale. This is far beyond what the schema alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three purposeful sentences with no wasted words. The core action is front-loaded, and the behavioral and safety details are presented efficiently with a clear rationale. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is nearly complete: it covers the operation, non-destructive behavior, conflict handling, and dirty-worktree refusal. The main gap is explicit documentation of the required id parameter—how it should be obtained and formatted—so an agent might still be uncertain about the exact value to pass.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The id parameter has no schema description, and the description only indirectly addresses it by saying the stash entry is 'applied by sha rather than by position.' This adds useful meaning but does not explicitly map 'sha' to the integer id parameter, and the wording is potentially confusing given id's integer type. The cwd parameter is already well described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Put interrupted work back'), the resource ('stash entry'), and the key distinguishing mechanism ('applied by sha rather than by position'). It is readily distinguishable from the only sibling tool, stash_list, because it describes restoration rather than listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: restoring stashed work back into a worktree. It also gives an explicit refusal condition ('Refuses if the target worktree is already dirty') and explains why. However, it does not name alternatives, such as stash_list for finding the relevant id, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It explicitly warns that the operation is DESTRUCTIVE and irreversible, discloses the automatic safety backup, and explains the confirmation gate. It also identifies the primary failure mode: restoring the wrong file leaves no undo.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences lead with the action, then front-load the critical safety warning. Each sentence adds either scope or risk information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive restore tool with three fully documented parameters and no output schema, the description gives an agent everything essential: what the tool overwrites, why confirmation is mandatory, what safety mechanism exists, and the primary failure mode. Return-value documentation is not necessary for safe invocation here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100 percent; every parameter already has a description, including the backup filename source, the confirm semantics, and the cwd default. The description reinforces the danger of confirm but adds no new parameter-level facts beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and object: restore a backup over the live tracker. This clearly places it among the backup tools and distinguishes it from siblings like db_backup and db_backups by direction, and from stash_restore by naming backups explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes the invocation context—restoring a backup over the working tracker—and states the required guardrail: confirm must be true and a safety backup is taken first. It does not name alternatives or give when-not-to-use guidance, but the context is clear enough for this destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 richly. It explains the freezing behavior of gates, that 'moot' closes without counting as a decision and is reversible via gate_reopen, that 'repose' rewrites the question and resets asked_count, and that both verdicts require evidence naming a path or commit. This goes well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the action, then gives the rationale, the timing, and the verdict semantics in a compact sequence. Every sentence earns its place, and there is no filler or repetition of schema field names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for a complex tool with no output schema: it covers purpose, when to use it, what each verdict does, reversibility, evidence requirements, and side effects. It does not describe the return/response shape or the context/recommendation parameters, but those are minor for an agent correctly invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 63%, leaving several parameters undocumented, but the description adds meaningful semantics to the verdict enum and evidence requirement: 'moot' is never a decision the principal did not take, and 'repose' resets asked_count. It does not individually explain context or recommendation, but the conceptual grounding it provides is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Re-check a pending gate against the tree as it is now.' It clearly distinguishes gate_reconcile from sibling tools like gate_raise, gate_decide, and gate_reopen by explaining that it addresses stale pending gates whose frozen questions may have been answered or invalidated by later work.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage directive: 'Run this over every pending gate before putting any of them to the principal.' It also references gate_reopen for reversibility. It does not explicitly state when not to use it versus all alternatives, but the context is strong enough for an agent to know when it applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so excellently. It reveals operation ordering, broad stash scope including untracked files, non-blocking behavior, and the specific hazard of force releasing a live worker's claim.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences deliver purpose, mechanism, a stated non-wait rationale, and force guidance without redundancy. Every clause adds information, and the most important safety caveat is placed at the end where it gets focused emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a side-effect-heavy shutdown with no output schema and no annotations, the description covers the main workflow, side effects, ordering, and risks well. It stops short of full completeness by not describing the return/confirmation format or explicitly pointing to stash_restore as the resumption path.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, which establishes a baseline of 3. The description adds real value by expanding force beyond its schema text into a deliberate kill-it action with a concrete risk, and by tying cwd to worktree behavior. actor remains undocumented in both, but its meaning is conventional enough not to be a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Wind the project down') and expands into concrete actions: broadcast stop, stash all uncommitted changes in every worktree, and record where each stash lives. This uniquely identifies oz_shutdown among siblings and also explains what 'shutdown' means in this system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit context on when to use force:true, calling it the deliberate 'kill it' form, and explains why the tool deliberately does not wait for workers. It does not name alternative sibling tools for partial or per-feature shutdown, so it falls just short of fully explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It discloses that this creates a new goal, warns that near-duplicates fragment the queue, and explains the conversational source of the name. It does not mention return values or duplicate-handling behavior, but for a simple create operation the stated behavior is substantial and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, with the core purpose front-loaded in the first clause. Every sentence carries operational value: timing, naming philosophy, prerequisite, and next step. There is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description provides enough context to call it correctly: when to call it, what name semantics to follow, what to check first, and what to do immediately after. Nothing essential for selecting or invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: cwd is well documented in the schema, but name has no schema description. The description compensates for name by explaining its conceptual origin — it comes out of the conversation, not user invention. This adds meaningful semantics beyond the bare string field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Create a goal', then adds distinctive constraints: 'that does not exist yet' and 'at the END of a definition session'. It also differentiates from nearby goal tools by explaining that the name emerges from conversation rather than being supplied up front, which separates it from goal_set and goal_refine.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: only at the end of a definition session, and only for goals that do not yet exist. It prescribes a prerequisite ('Check goal_list first') and a mandatory follow-up ('Follow immediately with goal_refine'), making the intended workflow unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![feature-tracker-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/spe-investigator/feature-tracker-mcp/badges/card.svg)](https://glama.ai/mcp/servers/spe-investigator/feature-tracker-mcp)

Score Badge

Copy to your README.md:

[![feature-tracker-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/spe-investigator/feature-tracker-mcp/badges/score.svg)](https://glama.ai/mcp/servers/spe-investigator/feature-tracker-mcp)