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

With no annotations, the description carries the full burden. It usefully discloses return semantics (ok=false means a violation) despite there being no output schema, but says nothing about permissions, whether it is strictly read-only, or what it does when no rules exist.

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

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

Two tight sentences with no waste; the core action is front-loaded and the result interpretation follows immediately.

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

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

For a two-parameter read-style tool with no annotations and no output schema, the description covers the action, inputs, and the key return signal. Minor gaps remain around the ok=true case and file path expectations.

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

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: 'change' is explained as a diff, plan or description, and 'files' as touched files. It lacks format details (e.g., repo-relative paths) but meaningfully covers both inputs.

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

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

The description states a specific verb (check) and resource (a proposed change) and names the comparison target (active constraint rules). It is clear what the tool does, though it does not explicitly distinguish itself from siblings like list_constraints or record_decision.

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

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

Usage is implied: you check a proposed change before applying it. There is no explicit when/when-not guidance and no named alternative (e.g., 'list_constraints first to see the rules'), so the agent must infer the workflow context.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does disclose that the tool is a retrieval returning active constraints and relevant decisions, and that it should be invoked before work begins, but it says nothing about read-only semantics, scope of 'in scope', or the limit/pagination behavior governing results.

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

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

Two sentences, zero filler, and the critical timing instruction is front-loaded before the return-value clause. Every sentence earns its place.

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

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

With no annotations, no output schema, and 4 undocumented parameters, the description covers the core intent and call timing but leaves real gaps: the path/paths relationship, the limit cap, and what 'active constraints in scope' concretely means in the response.

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

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

Schema description coverage is 0% across 4 parameters. The description implies the task and file-path inputs ('task description and/or file paths') but never clarifies the path vs paths duplication, nor mentions the limit parameter or its 1–50 range. 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.

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

States a specific verb+resource: returns active constraints in scope plus the most relevant decisions for a given task/path. An agent can tell it retrieves curated context rather than merely listing constraints or searching decisions. It does not explicitly contrast itself with siblings like list_constraints or search_decisions, keeping it at 4 rather than 5.

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

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

The opening imperative 'Call BEFORE starting work' gives explicit timing guidance, which is exactly the usage context an agent needs for a pre-work context fetch. It stops short of naming alternatives or exclusions (e.g., when to prefer search_decisions instead), so it is clear context without routing rules.

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

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

With no annotations, the description carries the full behavioral burden and falls short: it does not say whether links are additive or idempotent, whether a link can be removed, what the 'validate' flag changes, or what permissions are required. The mutation semantics of 'Link' are implied but never detailed.

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

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

A single front-loaded sentence with no padding; the verb and target domain come first. It is efficient, though the compressed 'files and/or commits' phrasing sacrifices some clarity for brevity.

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

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

For a 6-parameter mutation tool with no annotations, no output schema, and 0% parameter coverage, the single sentence is not enough. An agent cannot tell what 'validate' does, what the required 'id' identifies, or what a successful link produces.

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

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

Schema coverage is 0% across 6 parameters, so the description must compensate and largely doesn't. It usefully documents the requirement-id format (capability/requirement[#scenario]) and the kinds of targets (tests, files, commits), but leaves 'id' (the required key), 'validate', and 'files' unexplained.

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

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

The description states a specific verb+resource: it links a decision to requirement ids, tests, and commits. The 'SpecGate requirement ids (capability/requirement[#scenario])' phrasing makes the target domain concrete. It does not, however, distinguish itself from siblings like record_decision or supersede_decision.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative among siblings (record_decision, search_decisions, etc.). Usage is only implied by 'Link a decision to...' with no statement of at what point in a workflow this should be invoked.

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

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

With no annotations, the description carries the full behavioral burden. It does not state permissions, return format, pagination, or whether listing mutates anything, and 'list active constraints' sits awkwardly against an include_inactive flag that implies inactive ones are retrievable too.

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

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

A single tight sentence, front-loaded with the verb and resource. No wasted words, though the brevity comes at the cost of the missing details noted above.

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

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

For a two-parameter tool with no output schema and zero schema description coverage, the description leaves include_inactive and the return shape entirely undefined, so an agent cannot confidently invoke the filter options.

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

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

Schema description coverage is 0%, so the description must compensate. It loosely explains the path parameter's scope-filtering meaning but says nothing about include_inactive, leaving half the parameters undocumented anywhere.

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

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

States a clear verb+resource ('List constraints') with a scope qualifier ('active'). It distinguishes the tool reasonably from decision-centric siblings like record_decision and search_decisions, though it doesn't explicitly name an alternative listing tool.

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

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

The phrase 'optionally only those whose scope covers a path' hints at when the path filter applies, but there is no guidance on when to use this versus check_conflicts or search_decisions, and no explanation of include_inactive's role.

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

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

With no annotations, the description carries the full behavioral burden but only discloses the write destination (.decisions/) and ADR framing. It omits whether existing decisions are overwritten, permission/auth needs, reversibility, or side effects from constraint rules – all material 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.

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

Two tightly-packed sentences with the action and destination front-loaded and zero filler. Nothing needs trimming and the constraint/decision distinction is stated up front.

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

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

For a 14-parameter mutation tool with no annotations and no output schema, the description is far too thin. It gives no guidance on the ADR field set, the constraint rules syntax, or how this relates to supersede_decision, so an agent cannot fully populate or route the call from the description alone.

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

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

Schema description coverage is 43%, below the 50% threshold, so the description should compensate but instead only references the type enum and implicitly title. It adds no meaning for the other twelve parameters (context, decision, alternatives, consequences, rules, requirements, status, tags, supersedes, etc.), leaving constraint-specific fields unexplained.

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

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

Names a specific verb (Record), resource (ADR-style decision / constraint), and destination (.decisions/), and distinguishes the two modes via type="constraint". It stops short of differentiating from siblings like supersede_decision or list_constraints, so an agent must infer the boundary.

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

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

"Call after making a non-obvious choice" gives a clear triggering condition, which is more than nothing. However, it offers no exclusions and no routing to alternatives such as supersede_decision (for replacing an existing ADR) or link_requirement, which are likely relevant given the sibling list.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the default active-only filtering and how include_inactive/status override it, which is real behavioral context. It says nothing about ranking behavior, result caps, or permissions, leaving significant gaps for a read tool.

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

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

Two short sentences, no filler, and the search mechanism plus the default-scope caveat are both front-loaded before any agent needs to open the schema.

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

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

With no annotations, no output schema, and 0% schema description coverage on five parameters, the description should do more. It adequately covers default filtering and two of the five parameters but omits limit behavior, ranking/pagination, and any return-shape expectations.

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

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

Schema description coverage is 0% across five parameters, so the description must compensate and only partly does: it explains include_inactive and status semantics and implicitly maps 'decisions and constraints' to the type enum. The limit cap and the required query parameter's expected syntax are left undocumented.

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

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

States a specific verb (BM25 search) over a specific resource (decisions and constraints), which clearly separates it from write siblings like record_decision and supersede_decision and from the plain list_constraints enumerator. It does not explicitly name an alternative, 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.

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

The default filter clause ('Active (accepted/proposed) only unless include_inactive or status is set') tells the agent the conditions that broaden results, which is useful implied guidance. However, there is no explicit statement of when to search versus when to use list_constraints or get_context_for_task, so usage is only partially covered.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose real behavior: the old record is marked superseded and the two records are cross-linked, which is genuinely useful. It omits whether the operation is reversible, what permissions are needed, and what happens to the old record's tags/files/rules.

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

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

Two short sentences, front-loaded with the action and immediately followed by the state change. Every clause carries information and there is no filler.

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

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

For a 13-parameter mutation with no output schema and no annotations, the description explains the core write semantics but leaves parameter usage, permission requirements, and post-call state largely uncovered. It is minimally adequate rather than complete.

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

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

Schema description coverage is only 46% across 13 parameters, so the description is expected to compensate, and it does not mention a single parameter. The agent learns nothing from the description about how 'id' targets the old record versus how the many decision-body fields (rules, requirements, tests, alternatives) are supplied for the new one.

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

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

States a specific verb ('Replace') plus resource ('an existing decision/constraint') and the outcome ('new one'), so the agent understands this is a supersession writer rather than a plain create. It implicitly separates itself from record_decision, but never names it, so differentiation relies on inference.

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

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

The phrase 'existing decision/constraint' implies you should call this only when an older decision needs replacing, which is enough to distinguish it loosely from record_decision. There is no explicit when-to-use, when-not-to-use, or prerequisite statement, and no mention of first needing an id from search_decisions.

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