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 disclose meaningful side effects: a fresh id is assigned, the filename is derived from the title, the document is validated/rendered, and it is written to the ADR base directory. It does not cover failure modes (e.g. what happens if validation fails), overwrite protection, or permissions, leaving part of the mutation contract undeclared.

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 naming the action first, then the pipeline in sequence. No filler, no redundancy, appropriately sized for the tool's complexity.

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

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

An output schema exists, so return values need not be explained, and the parameter meaning lives in the rich $defs descriptions. The description adequately covers the write pipeline for a create tool; only failure/overwrite behavior is left implicit given the absence of annotations.

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?

Top-level schema coverage is 0% and the description adds no parameter detail. However, the referenced $defs (AdrBody, AdrFrontmatter, AdrOption) carry exhaustive per-field documentation, so an agent reading the schema still gets full parameter meaning; the description itself contributes nothing here.

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 ('Create a new ADR') and goes further by enumerating the operational pipeline: id assignment, filename derivation, validation, rendering, and write to the base directory. This distinguishes it from read/update siblings, though it does not explicitly differentiate itself from the parallel create_* family (e.g. create_dec).

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

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

The description says what the tool does but never states when to use it versus alternatives such as edit, update, update_section, or the other create_* document tools. No prerequisites, no exclusions, no routing guidance is given.

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

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

With no annotations, the description carries the full burden and does so richly: filename derivation from H1, body-only validation, a non-raising ValidateResult (valid=False, errors[].message capped at 300 chars) on failure, and the crucial fact that nothing is written in that case. That failure semantics disclosure is exactly what an agent needs.

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

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

The core action is front-loaded, but the text is padded with internal metadata -- ADR GUIDs, feat-110, GitHub issue #204, 'case 5 of the ADR 519d1206 chain' -- that adds no value for tool selection or invocation. Structure is a single dense run-on, which harms readability.

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

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

An output schema exists, yet the description still usefully states the return is frontmatter-only (no body) and points to get_dec for the full document, plus covers failure behavior. For a single-param creation tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0% and the single 'content' param has no schema description, so the description must compensate -- and it does by clarifying the input is 'body-only content' (not frontmatter), with the H1 title used for the filename. It adds real meaning, though it doesn't specify format/length constraints.

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

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

States a specific verb and resource ('Create a new decision') and then enumerates the concrete internal steps: assigns id, derives filename from the H1 title, validates body-only content, writes to the decision base directory. This clearly separates it from the get_dec/list_dec/parse_dec siblings.

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

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

It only gives one routing instruction -- use get_dec afterward to fetch the full document -- which is a follow-up pointer rather than explicit when-to-use vs alternatives guidance. There is no stated condition for choosing create_dec over, say, edit/update, nor any prerequisite guidance.

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

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

With no annotations, the description fully carries the behavioral burden and then some: it discloses that ids are NOT max+1 auto-generated, that validation failures return a non-raising ValidateResult and write nothing, that validation runs BEFORE the id-shape and FileExistsError guards, and that a compound failure short-circuits the guards. This is unusually rich pre-call context for an agent.

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

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

The core action is front-loaded, but the single mega-sentence is bloated with internal traceability an agent cannot use: ADR UUIDs (f14f125e-..., 519d1206), issue numbers (#204, feat-110), and 'case 5 of the ... workaround chain'. This noise crowds out the actionable content and makes the definition hard to parse.

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

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

For a tool with real complexity (non-raising validation, guard ordering, frontmatter-only return), the description covers creation semantics, error behavior, and the follow-up read tool well. Since an output schema exists it need not document the return shape in detail, and it does not need to; a minor gap is that no permissions/auth context is given.

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% and the schema gives only bare 'Id'/'Content' titles, so the description must compensate. It thoroughly explains the optional 'id' (caller-chosen, default feat-0-<slug-from-title>, no max+1). 'content' is characterized as body-only content validated against a schema with an H1-derived filename, though the accepted content shape itself is not spelled out.

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 first clause gives a specific verb and resource ('Create a new feature') and immediately elaborates the mechanics: id assignment, filename derivation from the H1, body validation, and the write. It is clearly distinguishable from sibling get_feat and the other create_* tools, since the resource is named.

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

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

It explicitly routes the agent to the follow-up tool ('use the corresponding get_feat tool to fetch the full document afterward') and frames the return value accordingly. It does not, however, say when to create a feat vs. a tsk/gol/req or any prerequisites for creating a feature document, so no exclusions are given.

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

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

With no annotations, the description carries the full burden and does so well: it discloses id assignment, filename derivation from the H1, that a validation failure returns a non-raising ValidateResult and writes nothing, and that only frontmatter (not the body) is returned. The remaining shortfall is the heavy embedding of internal ADR UUIDs and issue numbers (ADR f14f125e..., ADR 519d1206, issue #204, feat-110) that are not actionable for the calling agent.

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

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

The operative behavior is front-loaded in the first sentence, but the second sentence is a dense run-on of implementation trivia—ADR UUIDs, GitHub issue numbers, 'case 5 of the ADR 519d1206 non-raising-structured-result workaround chain'—that costs the reader without helping tool selection. Much of this should be dropped or tightened.

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

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

An output schema exists, so return-value explanation is optional, yet the description usefully notes frontmatter-only return and the follow-up get_gol call. The mutation path (nothing written on validation failure) is covered, leaving only parameter-format detail as a minor gap.

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

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

Schema description coverage is 0% for the single `content` parameter, so the description must compensate. It partially does by clarifying this is body-only content and that the H1 title drives the filename, but it never names the parameter explicitly or states format constraints (e.g. markdown vs plain text), leaving a 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?

The first clause states a specific verb (Create) and resource (goal), and the surrounding detail (assigns id, derives filename, validates body, writes to goal base directory) makes it unmistakably distinct from siblings like get_gol, list_gol, and parse_gol. An agent can identify the operation without inspecting the schema.

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

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

Usage is implied (create a new goal document) and it routes the agent to get_gol for the full document afterward. However, there is no explicit when-to-use guidance relative to the other create_* tools, nor any stated preconditions such as required permissions or where the base directory lives.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that validation failures return a non-raising ValidateResult (valid=False, errors[].message capped at 300 chars) rather than raising AssertionError/pydantic.ValidationError, and that nothing is written in that case. It also discloses the return shape (frontmatter only, no body).

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

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

Front-loaded with the primary action and effect chain, then behavior on failure, then return contract. Dense but largely earn-its-place; the internal ADR/issue/feat references are verbose and add noise for an agent deciding whether to call it.

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

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

For a single-input create tool with an output schema, the description is nearly complete: it covers effects, failure semantics, and return contract. The remaining gap is authoring guidance (no mention of get_prb_template/get_prb_example for body structure), which an agent would likely want.

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% and there is a single parameter, so the description must compensate. It clarifies that content is body-only and that its H1 title is used to derive the filename, which adds real meaning beyond the bare 'content: string' schema. It stops short of specifying expected body format or required sections.

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 ('Create a new Problem Statement') and enumerates the concrete effects: fresh id, filename derivation, validation, and write to the base directory. An agent can distinguish it from sibling create_* tools and from get_prb/parse_prb/list_prb without opening any schema.

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

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

The only routing guidance is a follow-up pointer: use get_prb to fetch the full document afterward. There is no explicit when-to-use versus edit/update/update_frontmatter, nor a pointer to get_prb_template for authoring the body, so context is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses id assignment, filename derivation from the H1 title, validation of body-only content, write target directory, that nothing is written on validation failure, and the non-raising ValidateResult contract with a capped error message. It also states that only frontmatter (no body) is returned. No annotation contradiction.

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?

Core behavior is front-loaded in the first sentence, and the critical return-contract and follow-up tool are stated clearly. The dense parenthetical citing ADR UUIDs, feat-110, and 'case 5 of the ADR chain' adds internal-reference clutter that a calling agent does not need.

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 create tool with an output schema present, the description covers what is written, what is not written on failure, the failure/result shape, and how to retrieve the full document. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0% and the single param is undocumented in the schema, but the description compensates by clarifying that content is 'body-only' and that a filename is derived from its H1 title, implying an H1 is expected. This meaningfully extends beyond the bare 'content: string' schema.

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

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

Opens with a specific verb+resource ('Create a new Question and Answer (QA) document') and enumerates the distinct operations performed (fresh id, filename derivation, body validation, write to QA base dir). This clearly distinguishes it from the sibling create_* tools for other document types and from get_qa.

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

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

The description explicitly routes the agent to the follow-up tool ('use the corresponding get_qa tool to fetch the full document afterward'), which is genuine guidance. However, it gives no when-not-to-use conditions and does not contrast with siblings like edit, update, or parse_qa.

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 does so well: it discloses the non-raising ValidateResult contract, the exact failure shape (valid=False, single errors[].message capped at 300 chars), and crucially that nothing is written on validation failure. It also states the return is frontmatter-only, which is not inferable 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.

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

The core behavior is front-loaded, but the paragraph is bloated with internal provenance that does not help tool selection: ADR UUIDs, GitHub issue #204, 'feat-110', and 'case 5 of the ADR 519d1206 workaround chain'. Those clauses cost tokens without guiding the agent.

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

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

For a single-parameter creation tool, all decision-relevant information is present: what it writes, how the id/filename are derived, error semantics, the no-write-on-failure guarantee, and what is returned. An output schema exists, yet the description still clarifies the return scope, leaving no gap for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate, and it does add real meaning: content is 'body-only' (frontmatter is derived, not supplied) and must contain an H1 title used for the filename. It stops short of describing validation rules or the expected markdown format, so it is not fully compensating.

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 (create a new requirement) and enumerates the exact operations performed: id assignment, filename derivation from the body H1, body validation, and write to the base directory. It also distinguishes itself from the retrieval sibling by pointing to get_req for the full document.

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

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

Explicitly routes the agent to get_req after creation to fetch the full document, which is clear follow-up guidance. However, it never states when NOT to use this tool (e.g., when a requirement already exists, or versus parse_req/list_req) or any preconditions, so it falls short of full when/when-not coverage.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so richly: it discloses the failure mode (non-raising ValidateResult with valid=False, errors[].message capped at 300 chars), that nothing is written on validation failure, and that only frontmatter is returned. This is substantially more than any annotation would convey.

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

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

The core behavior is front-loaded, but the middle is bloated with internal references – an ADR UUID, feat-110, GitHub issue #204, case 5 of a workaround chain – that are noise for an agent choosing or invoking the tool. These citations dilute an otherwise efficient description.

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

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

An output schema exists, so return values need not be fully explained, yet the description still usefully clarifies that only frontmatter (no body) is returned and that nothing is written on validation failure. Combined with the filename-derivation and validation disclosure, it is nearly complete; only the precise content format and error payload fields are left implicit.

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

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

Schema description coverage is 0% for the single 'content' parameter, so the description must compensate. It does add real meaning: the content is 'body-only', it is 'submitted body-only content' that gets validated, and its H1 title drives the derived filename – useful semantics the schema lacks. It stops short of describing the exact content format or whether frontmatter is permitted.

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 ('Create a new risk') and enumerates the exact side effects: id assignment, filename derivation from the H1 title, body validation, and write to the risk base directory. An agent can distinguish this from get_rsk and the other create_* siblings without opening any schema.

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

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

The description routes the agent to the follow-up tool ('use the corresponding get_rsk tool to fetch the full document afterward'), which is explicit. However, it gives no when-to-use guidance for creating a risk versus other document types, and no exclusions or prerequisites for the creation act itself, so usage is only implied.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the side effects (id assignment, filename derivation, write to the SOP base directory), the exact failure mode (non-raising `ValidateResult` with `valid=False` and a 300-char-capped error message, no write performed), and the return shape (frontmatter only, no body). This is behaviorally rich 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?

The purpose and outcome are front-loaded, but the middle is cluttered with internal identifiers (ADR UUIDs, issue #204, 'case 5 of the ADR... workaround chain', feat-110) that add no decision value for an agent and dilute the actionable content. Several sentences do not fully earn their 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?

The tool's behavior, failure path, and return contract are all covered, so an agent has enough to invoke it correctly. Because an output schema already exists, the sentence describing the frontmatter-only return is somewhat redundant, but the coverage is otherwise 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 coverage is 0% and the single `content` param is undocumented in the schema, but the description compensates: it specifies the argument is body-only content (no frontmatter) and that its H1 title drives the generated filename. That is meaningful added semantics beyond the bare `string` type.

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

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

Opens with a specific verb+resource ('Create a new Standard Operating Procedure') and enumerates the concrete lifecycle steps: id assignment, filename derivation from the H1 title, body validation, and write. It also explicitly names `get_sop` as the complementary tool, so an agent can separate it from the sibling `create_*`/`parse_sop` tools without opening schemas.

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

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

The description gives a clear follow-up step ('use the corresponding `get_sop` tool to fetch the full document afterward') but never states when to choose `create_sop` over alternatives such as `parse_sop`, `edit`, or `update_frontmatter`, nor any prerequisites for calling it. Usage is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that content validation failure returns a non-raising ValidateResult (valid=False, errors capped at 300 chars) instead of raising, that nothing is written in that case, and that only frontmatter is returned. This is behavior an agent cannot infer from schema or annotations.

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

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

Front-loads the main purpose well, but parenthetical citations (feat-110, ADR f14f125e-..., GitHub issue #204, ADR 519d1206) are internal-tracking noise that adds length without helping an agent invoke the tool.

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

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

An output schema exists so return-value detail is optional, yet the description still notes only frontmatter is returned and points to get_sysrs for the body. For a mutation tool with no annotations, all decision-relevant information an agent needs is present.

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

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

Schema coverage is 0% for the single content param, so the description must compensate, and it does: it specifies the value is 'body-only content' and that the H1 title drives filename derivation. Minor gap is that content format (markdown structure, size limits) is not spelled out.

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 precise verb (Create) plus resource (System Requirements Specification) and enumerates the internal steps: assigns an id, derives a filename from the H1 title, validates the body, and writes to the base directory. This clearly distinguishes it from sibling creators of other document types and from get_sysrs.

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

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

Explicitly instructs the agent to call get_sysrs afterward to fetch the full document, and indicates the input is body-only content. It stops short of stating exclusions versus the other create_* tools, but the routing context is clear.

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, and it does well: it discloses that invalid content returns a non-raising ValidateResult with a 300-char cap on error messages, that nothing is written in that case, and that only frontmatter is returned. It does not cover permissions, overwrite behavior, or id-collision handling.

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 very long run-on sentence packed with internal ADR hashes (f14f125e...), a GitHub issue number, and a feat-110 tag. The routing guidance ('use get_tsk') is buried at the end, and the traceability jargon is not actionable for an agent selecting or invoking the tool.

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

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

Given a single required param, no annotations, and an existing output schema, the description covers the essential operational facts: validation behavior, what is returned, and the follow-up tool. An output schema existing means return values need not be explained, which the description respects.

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

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

Only one parameter (content) with 0% schema description coverage. The description clarifies that content is 'body-only' and validated, and that the H1 title drives the filename, which adds real meaning beyond the bare schema. But it doesn't specify accepted formats or validation rules that the agent could anticipate.

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

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

States a specific verb and resource (create a new task list) and enumerates concrete sub-steps: fresh id assignment, filename derivation from the body's H1, content validation, and document write. This clearly distinguishes create_tsk from the many sibling get_/list_/parse_/create_ tools across other artifact types.

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

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

Explicitly tells the agent to use get_tsk afterward to fetch the full document, since only frontmatter is returned. However, it gives no guidance on when to prefer create_tsk over create_* siblings for other artifact types, or any preconditions (e.g., where the body must come from).

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses id assignment, filename derivation, validation of body-only content, the non-raising ValidateResult on failure (valid=False, capped error message) instead of raising AssertionError/ValidationError, that nothing is written on failure, and that only frontmatter is returned.

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

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

Front-loaded with the core purpose, but the middle sentence is a dense run-on laden with internal identifiers (ADR UUIDs, feat-110, GitHub issue #204, case numbers) that add little for an agent selecting or invoking the tool. Those references inflate length without improving the call decision.

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

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

The output schema exists, so return values need not be detailed, yet the description still helpfully notes frontmatter-only returns. For an unannotated mutation tool it covers creation and failure behavior well, though it omits overwrite/permission behavior and whether the body requires a title.

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%, so the description must compensate, and it does clarify that content is the complete body-only content (no frontmatter) and that its H1 title is used to derive the filename. It does not state format requirements (e.g., whether an H1 is mandatory), leaving a small 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 and resource ('Create a new use case') and enumerates the concrete mechanics (fresh id assignment, filename derivation from the H1 title, validation, write to the use-case base directory). An agent can distinguish it from get_uc, parse_uc, and edit/update without opening any schema.

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

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

Explicitly routes the agent to get_uc for fetching the full document after creation, which is genuinely useful follow-up guidance. However, it gives no guidance on when to prefer create_uc over parse_uc/edit/update, and the creation context itself is only implied.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses id generation, filename derivation from the H1 title, that nothing is written on validation failure, and the non-raising `ValidateResult` (`valid=False`, `errors[].message` capped at 300 chars) instead of `AssertionError`/`pydantic.ValidationError`. It does not cover other operational traits such as permission/auth requirements, behavior on filename collisions, or I/O error surfaces, so it is strong rather than complete.

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

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

The core behavior is front-loaded in sentence one, but the middle sentence is bloated with internal identifiers ('feat-110', ADR UUIDs, 'GitHub issue #204 -- case 5 of the ADR 519d1206 non-raising-structured-result workaround chain') that an invoking agent cannot act on. Trimming those would preserve all usable meaning in roughly half the tokens.

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

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

An output schema exists, so return values need not be spelled out, yet the description still adds value by stating the return is frontmatter-only with no body and pointing to get_vcr for the full document. Given a single-parameter mutation tool with no annotations, this covers calling behavior adequately; the remaining gap is failure handling outside the validation path.

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 for the single bare `content` string. It does: 'submitted body-only content' clarifies frontmatter must be excluded, and it explains that the H1 title inside the content drives the generated filename. It stops short of stating whether an H1 is mandatory or what format/encoding is expected.

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

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

States a specific verb and resource ('Create a new verification case record') and enumerates the concrete side effects: fresh id assignment, filename derivation from the H1 title, validation, and write to the VCR base directory. An agent can distinguish this from sibling create_* tools and from get_vcr/parse_vcr/list_vcr without opening anything else.

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

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

Explicitly names the follow-up alternative: 'use the corresponding `get_vcr` tool to fetch the full document afterward,' which resolves the natural next-step question after a write. However, it never states prerequisites or when NOT to use this (e.g., when to prefer parse_vcr or how a failed validation should be handled by the caller beyond noting nothing was written).

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

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

With no annotations, the description carries the full burden and does so: it discloses the domain lock acquisition, destructive permanence, the differing removal semantics for flat vs. feat domains, and three distinct error classes (ValueError raised before any file access, XNotFoundError, DeleteError). That is unusually rich behavioral context 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?

Dense but front-loaded: the destructive action and scope come first, then resolution mechanics, then error taxonomy. Every clause carries information, though the parenthetical enum recital partially duplicates the schema enum and could be trimmed.

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 destructive two-parameter tool with no annotations, the description covers what gets destroyed, how lookup and locking work, the return value, and all failure modes. With an output schema present, it need not expand further on response shape.

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, and it does: it enumerates the accepted type values, explicitly excludes `adr`, and explains that `id` is resolved with validation against path-injection and wrong formats before file access. Both parameters gain meaning beyond the bare enum and string type.

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

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

States a specific verb and resource ('Permanently delete an existing document') plus the domains it applies to and the exact filesystem effect (single .md file vs. whole <base>/<id>/ folder). An agent can distinguish this from the many create_/get_/list_/parse_ siblings without opening the schema.

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

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

Explicitly frames itself as 'the sole delete entry point -- the former per-domain delete_<d> tools are removed', which resolves routing against siblings. There is no when-not-to-use guidance, but since no alternative delete path exists there is nothing to disambiguate further.

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 and does so thoroughly: two-stage matching/validation, atomic disk write with byte-unchanged file on failure, non-raising ParseFailureResult and ValidateResult vs. raised ValueErrors/not-found errors, and explicit byte-exact rules (no line-ending normalization, no BOM, no fuzzy/regex fallback). This is exceptional behavioral disclosure for an unannotated 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?

Front-loads the core purpose and the update-vs-edit distinction before diving into mechanics, and every clause arguably carries needed behavior (atomicity, error taxonomy, matching rules). It is nonetheless a dense single block that is far longer than typical, bordering on overwhelming, which is the only structural weakness.

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?

Fully complete for a 5-param mutation tool: success return ('updated frontmatter only, no body, `updated` bumped'), all failure modes, atomicity guarantees, and guidance to fetch the full document via get_<d> afterwards. Even though an output schema exists, the description still rounds out the operational picture.

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 and it does: `old_str` must match byte-exactly and uniquely unless `replace_all` is true, `new_str` empty means pure deletion, `replace_all` rewrites every occurrence, `id` shape is validated before any file access, and `type` enumerates the supported domains while excluding `adr`.

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 precise verb+resource ('surgical, exact-match string replacement of an existing document's frontmatter-stripped body') and immediately names the sibling it is not ('the generic `update` tool for a whole-body or line-range replacement'). An agent can distinguish edit from update without opening either schema.

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

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

Explicitly names the alternative tool (`update`) and the condition that selects it, plus the read-before-edit step via the corresponding `get_<d>(id, raw=True)` and the caveat that it is a client convention, not server-enforced. When-to-use and when-not-to-use are both stated.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the embedding backend, the feature-disabled path returning `{available: false, reason, message}` instead of raising, error semantics (`ValueError` before any filesystem access for bad args, the domain's `XNotFoundError` for a missing source), the unparseable-candidate edge case (`id = null`, `<failed to parse>` marker), and the sorted/excluded result behavior.

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

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

Purpose and scope are front-loaded in the first sentence, followed by filtering, result shape, edge cases, and error behavior in a sane order. It is a dense single block with no visual structure, and a few clauses (e.g., the backend name) are borderline detail, but nearly every sentence earns its place.

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

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

For a 5-parameter similarity-search tool with an output schema, the description covers invocation constraints, defaults, filtering, failure modes, and the feature-disabled return path. Even though an output schema exists, the row shape is described as a bonus. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description had to compensate and largely does: `top_k` is documented with its default and validated 1..100 range, `min_score` as an inclusive cosine lower bound with no default filter, `target_types` as the restriction mechanism, and `type`/`id` as the source identifier. This is meaning well beyond the bare schema property names.

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

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

States a specific verb and resource ('Find the documents most semantically related to an existing document, given its type/id') plus the ranking basis (cosine similarity of local sentence embeddings). Very clear what it does. It does not, however, explicitly differentiate itself from the sibling find_similar_text (doc-to-doc vs. text-query search), so an agent could still hesitate between the two.

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

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

The description gives useful scoping context: by default all whole-body domains are searched, `adr` is structurally excluded, the source doc is omitted, and `target_types` narrows the search. But it never states when to prefer this over find_similar_text or any other alternative, nor describes exclusions like 'use X instead when you only have raw text'.

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

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

With no annotations, the description carries the full burden and does so thoroughly: default domain coverage with adr structurally excluded, the fallback `{available: false, reason, message}` result when the embedding feature is disabled or fails to load, the unparseable-candidate behavior (id=null, `<failed to parse>` marker), and that bad target_types/top_k raises ValueError before any filesystem access.

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

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

Front-loaded with the core purpose, then progressively adds ranking method, scope, return shape, and failure modes. Every clause carries information, but the single long paragraph with heavy parenthetical nesting is denser than ideal for scanning.

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 four-parameter search tool with no annotations, the description covers scope, ranking, defaults, return fields, and error/fallback behavior. An output schema exists, yet the description still gives the row shape without over-explaining, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate and it does: query is free-form, top_k defaults to 10 and is validated 1..100, min_score is an inclusive cosine lower bound with no filter by default, and target_types restricts the enumerated domain list. This adds real meaning beyond the bare schema types.

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 precise verb+resource: find documents most semantically similar to a free-form query text, ranked by cosine similarity of local embeddings. This distinguishes it cleanly from the get_*/list_*/find_related siblings, which retrieve by identity or reference rather than semantic similarity.

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

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

Gives explicit context ('for pre-creation dedup/discovery checks'), telling the agent when this tool is the right choice. However, it never names an alternative or a when-not condition (e.g. versus find_related or list_*), so routing is implied rather than spelled out.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses an error trait ('An invalid id ... is a ValueError raised before any file access'), confirming read-only access and failure semantics, but says nothing about permissions or how the read behaves on a valid-but-missing id.

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

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

Two sentences with zero waste, front-loading the core action and following with the notable failure mode. Nothing is padded or repeated from 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 an output schema present, return-value details are unnecessary, and the description covers purpose plus error behavior for a one-parameter getter. The main gap is the absence of usage/routing guidance relative to the many sibling get_* tools.

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, and it does add meaning: the single 'id' identifies a specific ADR and must be a valid format (rejecting path-injection). This goes beyond the bare 'Id' string in the schema, though it stops short of documenting the id's accepted format or source.

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

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

States a specific verb and resource ('Read, parse, and return a full ADR document (frontmatter and body) by its id'), and the '(frontmatter and body)' detail clarifies scope versus a lighter-weight read. It does not explicitly differentiate itself from siblings like list_adr or validate_adr, but the purpose is unambiguous.

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

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

It implies you fetch a single document 'by its id' but gives no when-to-use guidance, no prerequisites, and never names an alternative such as list_adr or validate_adr. An agent must infer the retrieval context on its own.

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

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

With no annotations, the description carries the full burden and does so thoroughly: invalid ids raise ValueError before any file access, out-of-range offset/limit clamp (offset > N returns empty string), parse failures return a ParseFailureResult rather than raising, and note/body numbering never restarts under windowing. It also discloses cross-tool consistency of error text, which exceeds typical disclosure.

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

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

The core is front-loaded in sentence one, but the rest is a single dense paragraph packed with asides — an ADR UUID, a note about a trailing pydantic documentation line, byte-identical error text across tools. These details crowd out scannability and do not all earn their place for an agent trying to call the tool.

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

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

An output schema exists, so return-shape explanation is optional, yet the description still covers the meaningful output variants (raw body, numbered lines, ParseFailureResult). For a 5-parameter tool with zero schema descriptions, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate and it does: id (lookup by id), raw (frontmatter-stripped verbatim mode), offset (1-based, default 1), limit (line count, default through end), numbered (prefix format '<n>: ', absolute body-line numbers). Defaults, units, and interaction rules are all stated.

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 opening sentence gives a precise verb+resource+identifier: 'Read, parse, and return a full decision document (frontmatter and body) by its id.' The raw=True branch is also defined as a distinct mode. However, it never contrasts itself with nearby siblings such as parse_dec, get_dec_template, or get_dec_example, so the agent must infer the boundary from the name.

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?

Clear conditional guidance: use raw=True for verbatim frontmatter-stripped body text, offset/limit for windowed reads, numbered when line numbers are needed for `update`'s offset. The 'when-not' is present for parameter combinations (numbered/offset/limit with raw=False raise ValueError) and for feeding numbered output into content/old_str. No explicit alternative-tool routing among siblings, so it stops short of 5.

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

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

No annotations are supplied, so the description carries the burden alone. It does disclose meaningful traits: the output is raw markdown with both frontmatter and body, it is complete and valid, and it 'exercise[s] every section' — telling the agent the sample is exhaustive rather than minimal. It stops short of saying whether the sample is static or parameterized, but the zero-parameter schema makes that moot.

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 sentence, front-loaded with the verb and resource, with the qualifiers ('frontmatter and body', 'every section') placed as trailing detail. Every clause earns its place and nothing is padded.

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

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

An output schema exists, so return structure need not be restated, and the description adds the useful fact that the content is markdown with frontmatter plus an exhaustive section set. Complete enough to call correctly, though a note on whether the example is a fixed canned file would remove the last ambiguity.

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

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

The tool takes no parameters (0 params, 0 required), so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly avoids inventing parameter talk.

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

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

States a specific verb ('Return') and resource ('sample decision document') plus the exact payload shape ('raw markdown -- frontmatter and body'). This cleanly separates it from sibling get_dec (a real document), get_dec_template (a blank skeleton), and create_dec, without needing to name them.

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?

'For use as a learning example' implies the usage context but never states when to prefer this over get_dec, get_dec_template, or get_dec_example's many sibling example tools. No exclusions or prerequisites are given; an agent must infer the routing.

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 disclosure burden and does a fair job: it specifies the output is raw markdown, contains both frontmatter and all body fields, and that the body is filler ('blind text') rather than real content. It omits stating that the call is side-effect free and static, but nothing here misleads.

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?

One sentence, front-loaded with the action and payload, and the 'blind text' parenthetical clarifies the placeholder nature without padding. Nothing is wasted.

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

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

An output schema exists, so the description needn't spell out the return structure, and it doesn't have to (no params either). What it does provide — content shape and intended use — is enough for an agent to call it correctly; only the sibling differentiation is missing.

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

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

Zero input parameters, so there is no parameter semantics to convey and nothing for the description to compensate for. Baseline 4 applies.

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

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

States a specific verb and resource ('Return a DEC document template') and details exactly what the payload contains: frontmatter plus every body field with placeholder text, as raw markdown. It does not differentiate itself from the near-identically named sibling get_dec_example, but the purpose itself is unambiguous.

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

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

It gives a clear intended context ('for use as a starting point when drafting a new decision'), which implies when to reach for it. However, it never names alternatives or exclusions, so an agent must infer the template-vs-example-vs-get_dec distinction from the naming alone.

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

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

With no annotations provided, the description carries the full behavioral burden and does add substantive context: parse failures return a ParseFailureResult rather than raising, invalid ids raise ValueError before file access, out-of-range offset/limit clamp, and conflicting parameters raise ValueError. The dense ADR cross-references and warmup-qualification discussion (ADR 3982712a, ADR 9080b37c) are far more detail than any agent needs and dilute the useful signal, keeping it from a 5.

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

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

The core content is front-loaded correctly (purpose and raw mode first), but the middle section balloons with ADR identifiers, warmup timing, and byte-identity qualifiers that serve maintainers rather than an agent selecting or invoking the tool. Substantial trimming would preserve all actionable information.

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

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

For a 5-param read tool with an output schema (so return values need not be re-explained), the description covers modes, parameter interactions, failure modes, and cross-tool round-tripping warnings adequately. The completeness is undermined only by the inclusion of internal ADR/warmup detail that doesn't help an agent call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it explains raw, offset/limit semantics (1-based, defaults, clamping, interaction with raw=False), and numbered (line-number prefix format, offset-relative numbering, only valid with raw=True). The only required param, id, gets modest treatment (described mainly via its ValueError failure modes), leaving a small gap that prevents a 5.

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: read, parse, and return a full feature document (frontmatter and body) by id, plus the raw=True variant returning the frontmatter-stripped body verbatim. It's clear what the tool does, but it doesn't distinguish itself from sibling getter tools like parse_feat or list_feat beyond the incidental listing of list_feat's error behavior, so it falls 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?

Usage is implied through mode/parameter descriptions (use raw=True for verbatim body, offset/limit for windowing, numbered=True for line numbers) rather than explicit when-to-use/when-not guidance. The description repeatedly names alternatives (list_feat, update, create_feat, edit) but mostly as caveats about error text or round-tripping, not as routing guidance for choosing this tool over parse_feat or list_feat.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return format (raw markdown with frontmatter and body, exercising every section) and implies a read-only, parameterless fetch, but it says nothing about whether the output is static or whether it costs anything to call. It covers the essentials without richness.

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 that identifies the action, the format, and the purpose with no filler.

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

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

An output schema exists, so the description need not explain return values, and it still characterizes the payload as complete raw markdown covering every section. For a zero-parameter sample getter this is nearly everything an agent needs, with sibling differentiation the only real gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

Names a specific verb and resource (return a sample feature document) and states the artifact's shape (frontmatter plus body, every section). The phrase 'for use as a learning example' implicitly distinguishes it from get_feat/get_feat_template, but the description never names those alternatives, so 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.

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

'for use as a learning example' implies the intended context, but there is no explicit when-to-use guidance and no statement of when to prefer get_feat_template or get_feat instead. Adequate but inferential.

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 supplied, the description carries the full burden and does disclose meaningful behavior: the exact return shape (raw markdown, frontmatter plus all body fields) and that the content is placeholder 'blind text' rather than real data. It never explicitly states this is a non-mutating read with no side effects, which is the only notable gap.

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

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

A single front-loaded sentence that opens with the verb and resource. The parenthetical gloss on 'blind text' is slightly indulgent but the sentence remains efficient overall.

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

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

For a zero-parameter tool with an output schema already defining the return structure, the description is essentially complete: it covers what is returned, in what format, and for what purpose. Only the missing sibling differentiation keeps it from being fully airtight.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies. There is nothing parameter-level for the description to clarify.

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

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

States a specific verb and resource ('Return a FEAT document template') and details the payload (frontmatter plus every body field, placeholder content, raw markdown). It does not, however, distinguish itself from the closely named sibling get_feat_example, leaving the template-vs-example boundary implicit.

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?

'for use as a starting point when drafting a new feature' gives a clear context for use, but there is no guidance on when not to use it or why an agent would pick this over get_feat_example or get_feat. Usage is implied rather than explicitly routed.

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

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

With no annotations, the description carries the full burden and discharges it well: parse failures return a ParseFailureResult instead of raising, invalid ids raise ValueError before file access, out-of-range offsets clamp to empty string, and mutually exclusive flag combinations raise ValueError. It even documents cross-tool error-text consistency, far beyond what structured fields provide.

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

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

Purpose is front-loaded, but the body is a dense run-on block of extremely long compound sentences with parenthetical clause stacking and an ADR citation, which hurts scanability. The detail is proportionate to a 5-parameter tool, but structure and sentence length could be tightened.

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

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

An output schema exists, so return-value documentation is not required, and the description still adds error/edge-case semantics that the schema cannot express. It is essentially complete for this read tool, with only minor gaps such as id format specifics.

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%, so the description must compensate and largely does: raw, offset (1-based, default 1), limit (default through end of body), and numbered (format '<n>: ', numbers do not restart after windowing) are all explained with defaults and interactions. Only the id parameter's format is left partly implicit ('path-injection attempt or wrong format').

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 opening sentence states a specific verb and resource: 'Read, parse, and return a full goal document (frontmatter and body) by its id.' That is unambiguous and actionable. It stops short of explicitly distinguishing itself from siblings like parse_gol or get_gol_template, so it is clear but not sibling-differentiating.

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

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

The description gives conditional usage for parameters (raw=True for frontmatter-stripped body; numbered only meaningful with raw=True) and warns where the output must not be reused. However it never states when to choose get_gol over parse_gol/list_gol, so the when-to-use-this-vs-alternative guidance is only implied.

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

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

With no annotations, the description carries the burden and discloses the return format ('raw markdown -- frontmatter and body') and content scope ('exercising every section'). It does not explicitly state read-only safety or side effects, but the verb 'Return' strongly implies a read operation.

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

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

The description is a single front-loaded sentence that states the action, output format, content scope, and intended use without any wasted words.

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

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

Given the tool has no parameters, an output schema, and no annotations, the description is complete enough. It explains what the example contains and its learning purpose, leaving return-value details to the output schema.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds no parameter meaning because none exists, which is appropriate.

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

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

The description names a specific verb and resource: 'Return a complete, valid sample goal document as raw markdown.' It also distinguishes this tool from sibling get_gol, get_gol_template, and create_gol by clarifying that the output is a fully populated learning example exercising every section.

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 'for use as a learning example' gives clear context for when to call this tool. It does not explicitly name alternatives or exclusions, but the intended use is unambiguous.

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

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

No annotations are provided, so the description carries the burden and does well: it discloses the return format (raw markdown), the content shape (frontmatter + every body field, all populated), and the placeholder nature of the content. It does not mention safety/permissions or that repeated calls yield identical output, but for a read-only template fetch those are minor omissions.

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 sentence with the outcome front-loaded and the qualifying details (format, placeholder content, intended use) trailing. No redundancy or filler; every clause carries information.

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

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

For a zero-parameter template retrieval tool with an output schema, the description fully covers what an agent needs: what is returned, in what format, and why it would be called. Return-value details are already backed by the output schema.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies there is nothing to configure by describing a static template with no 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?

States a specific verb (Return) and resource (GOL document template) plus the exact payload: frontmatter and every body field filled with placeholder 'blind text'. The phrase 'template ... populated with placeholder content' distinguishes it functionally from the sibling get_gol_example (filled real content) and get_gol (an existing goal) without ambiguity.

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

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

The description names the use case explicitly: 'for use as a starting point when drafting a new goal'. That is a clear trigger condition, but it does not name the alternatives it should be chosen over (get_gol_example, get_gol) or state exclusions, 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.

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

No annotations are provided, so the description must carry the full behavioral burden. It does disclose parse-failure behavior (returns ParseFailureResult instead of raising), ValueError conditions for invalid ids and parameter combinations, clamping of out-of-range offsets, and the numbered-line caveat about not feeding output back into content. That is substantial behavioral disclosure, though it could mention permissions or file-access timing more explicitly.

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

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

The description is a single very dense, run-on paragraph that is difficult to parse. Multiple unrelated behaviors (parse failure representation, id validation, numbered line format, update/content feedback warnings) are packed into one block without front-loading the primary use case. It is thorough but lacks structural separation, hurting readability.

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

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

Given five parameters, no annotations, and the presence of an output schema, the description is mostly complete: it covers return-shape variations, error modes, parameter interactions, and cross-tool usage warnings. It omits any note about when the output schema applies versus raw=True, and does not mention potential rate limits or performance considerations, but those are minor given the tool's apparent nature.

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, and it largely does: offset is defined as 1-based first body line, limit as line count, raw as frontmatter-stripped toggle, and numbered as a line-prefix option meaningful only with raw=True. It explains default and interaction semantics for all four optional parameters, though it does not fully specify the format of id (`id` is only described by example).

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

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

The description opens with a specific verb+resource: 'Read, parse, and return a full problem statement document (frontmatter and body) by its id.' It distinguishes the tool from siblings like parse_prb and list_prb by specifying that it returns the parsed document, and clearly states the alternative behavior with raw=True (stripped body verbatim).

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

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

It explains when raw=True should be used (to get stripped body text) and when offset/limit apply, but it does not explicitly say when to choose get_prb over alternatives like parse_prb or get_prb_template, nor does it state any prerequisites. Usage is implied by the parameter interactions rather than an explicit when-to-use rubric.

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

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

With no annotations the description carries the burden, and it discloses the output shape (raw markdown, frontmatter plus body, exercising every section) and implies a safe, side-effect-free read via 'Return'. It could be more explicit that this is a read-only, non-mutating retrieval, but for a zero-parameter tool the behavioral profile is largely covered.

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 that states the return content, format, and intended use with no filler. Every phrase 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?

An output schema exists, so return values need not be spelled out, and the description still summarizes them. For a simple no-arg read tool this is complete, though the sibling relationship to get_prb_template is left unaddressed.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading or missing parameter guidance is present.

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

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

States a specific verb (Return) and resource (complete, valid sample problem statement document as raw markdown with frontmatter and body). It conveys the artifact well, but does not distinguish itself from close siblings like get_prb_template or get_prb, leaving the agent to infer the difference.

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 trailing clause 'for use as a learning example' implies when to reach for it, but there is no explicit when-to-use, when-not, or named alternative (e.g. get_prb_template for scaffolding, get_prb for real data). Usage is implied rather than stated.

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

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

No annotations are supplied, so the description carries the behavior burden alone. It usefully discloses that the returned markdown is placeholder/'blind text' rather than real data, which prevents misuse, but it says nothing about size, whether the content is static, or any side effects (a read-only generator is implied but never stated).

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

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

A single front-loaded sentence with no filler; the purpose ('Return a PRB document template') arrives immediately. The em-dash parenthetical about placeholder content is slightly heavy but still earns its place by clarifying the payload.

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

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

An output schema exists, so the description need not enumerate return values, and it doesn't attempt to. For a zero-parameter template getter it is nearly complete; the only missing piece is disambiguation from get_prb_example and get_prb_template's role in the create/draft workflow.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no input is required to obtain the template.

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

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

States a specific verb and resource ('Return a PRB document template ... as raw markdown') and describes the exact payload: frontmatter plus every body field filled with placeholder content. What it does not do is distinguish itself from the sibling get_prb_example, which an agent could easily confuse with a template getter.

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 implied usage ('for use as a starting point when drafting a new problem statement'), which gives some context. However, no alternative is named or excluded — notably get_prb_example and get_prb — and there is no guidance on when a drafting agent should pull the template rather than an existing record or example.

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 present, the description carries the full behavioral burden and does so thoroughly: parse failures return a ParseFailureResult instead of raising, invalid ids raise ValueError before any file access, offset/limit out-of-range values clamp, and combining offset/limit/numbered with raw=False raises ValueError. It even documents the anti-pattern of feeding numbered output back into content or edit old_str.

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

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

The purpose is front-loaded and most content earns its place, but the whole definition is a single dense paragraph riddled with nested parentheticals, an ADR UUID, and low-value detail about byte-identical pydantic trailing lines. Bullet points or shorter clauses would convey the same constraints with far less parsing effort.

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

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

Given five parameters, a required id, an output schema, and no annotations, the description covers everything an agent needs: mode selection, windowing semantics, error/exception behavior, and cross-tool constraints. Return-value shape is partly handled by the output schema, so no meaningful gap remains.

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, and it does: raw is defined as a verbatim frontmatter-stripped mode, offset is 1-based with default 1, limit is a line count defaulting to end-of-body, and numbered is defined only under raw=True with absolute line numbers that do not restart at 1. This is far beyond the bare type/default information in the schema.

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

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

The first sentence states a specific verb (read/parse/return) and resource (full QA document, frontmatter and body) keyed by id, which is unambiguous. It also names two modes (raw=False default vs raw=True). However it never explicitly contrasts itself with the adjacent siblings parse_qa or get_qa_template, so an agent still has to infer which sibling is appropriate.

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

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

The description gives clear in-tool usage context: pass raw=True for frontmatter-stripped body text, use offset/limit to window raw reads, and use numbered=True only with raw=True, including the routing hint that numbered line numbers can be fed back into update's offset. It does not, however, state when to choose this tool over the sibling parse_qa/list_qa/get_qa_template tools.

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, and it does disclose meaningful traits: the return is raw markdown, includes both frontmatter and body, and is guaranteed complete and valid with every section exercised. That is well beyond a bare restatement, though it says nothing about read-only safety or size/cost of the payload.

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 sentence with the action and the return shape front-loaded, then the qualifiers (frontmatter, body, every section) and the intended use. Every clause earns its place with no padding.

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 an output schema present, the description need not explain return values, and it already characterizes the payload's format and completeness. For a zero-parameter example tool this is nearly complete; the only omission is an explicit tie-breaker against get_qa_template and the other get_*_example siblings.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. The description adds no parameter detail, but none is required.

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

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

The description states a specific verb and resource ('Return a complete, valid sample QA document') and specifies the exact output shape (raw markdown, frontmatter and body, every section exercised). It is clearly distinct in spirit from the many sibling example tools, but it never names the closest sibling alternative, get_qa_template, which a reader must infer is the fill-in-the-blank counterpart.

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 'for use as a learning example' implies a usage context, but there is no explicit when-to-use, when-not-to-use, or alternative routing. An agent choosing between get_qa, get_qa_template, and get_qa_example gets only an implied signal rather than a stated rule.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return format (raw markdown), that all fields are present, and that content is placeholder blind text -- useful non-obvious details. But it says nothing about whether the template is static, whether it reads any source, or its safety/read-only nature.

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?

Single dense sentence with the resource front-loaded and the output format and placeholder nature all earned. No filler.

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

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

With no parameters and an output schema present, the description needn't explain return values structurally. It states the format and placeholder nature, which is enough to call correctly; only the static/read-only nature is left unstated.

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

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

Zero parameters, so the baseline of 4 applies; the description appropriately focuses on the return payload instead. Nothing further to document.

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

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

States a specific verb (Return) and resource (QA document template) and precisely describes what content is returned: frontmatter, every body field, and placeholder blind-text content, as raw markdown. Draws a clear line against get_qa (an existing document) and get_qa_example (an example) among many sibling template tools.

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

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

Explicitly states the use case -- as a starting point when drafting a new QA document -- which disambiguates it from get_qa and get_qa_example. No explicit when-not-to-use or alternative routing, though the sibling set makes the intent fairly clear.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the guard order (id/depth ValueError raised before any filesystem access), the exact error taxonomy (XNotFoundError, ParseFailureResult with byte-identical error text per ADR references), and the non-raising failure path. This is unusually rich behavioral disclosure.

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

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

The purpose is front-loaded and every clause carries information, but the whole body is a single dense wall of text laced with ADR codes and specmgr:// URI jargon. Bullet-separating the per-parameter semantics would improve scannability without losing content.

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, no-annotation, complex rendering tool, this is complete: it covers purpose, all parameter semantics, error behavior, guard ordering, and the post-call validation step. With an output schema present, the return contract is adequately signaled by the explicit note that the result is PlantUML source.

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%, so the description must compensate, and it does: it defines type (the source's domain with all 13 enum values implied), id (the source's own identifier, with format constraints for feat), depth (1..5 forward BFS depth), reverse (additive forward + direct-only incoming), include_feat (drops FEAT nodes and touching edges), and title (overrides H1, sanitized, never truncated).

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

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

The description opens with a specific verb and resource: 'Render and return the deterministic PlantUML component diagram of one source document's reference neighbourhood'. The scope ('one source document') implicitly distinguishes it from the sibling get_reference_diagram_all, and the output type (PlantUML source, not a specmgr document) is stated explicitly.

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

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

It gives clear operational guidance: use list_feat to discover the exact feat id, and run the result through validate_plantuml or specmgr plantuml-check for a verdict. It does not, however, explicitly state when to prefer this tool over sibling diagram tools such as get_reference_diagram_all, get_uc_diagram, or get_use_case_package_diagram.

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 provided, so the description carries the full burden and does so thoroughly: broken documents are skipped and 'the render never fails for content', truncation limit SPECMGR_DIAGRAM_MAX_TITLE (default 40) is disclosed, title is 'sanitized but never truncated', and it clarifies the return is PlantUML source, not a specmgr document. That is exactly the behavioral detail an agent needs to call and consume this tool safely.

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 dense paragraph that is front-loaded with the primary purpose, but the long clause chain listing diagram construction rules (cycles, unresolved nodes, edge syntax) is hard to parse and could be tightened. Every element is arguably useful, but the density hurts scanability.

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

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

Despite an output schema existing, the description correctly focuses on what the output IS (PlantUML source, not a specmgr document) and how to validate it — the one thing the schema can't convey. Combined with parameter behavior and rendering guarantees, an agent has everything needed to invoke and consume this tool correctly.

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

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

Schema coverage is 0% and both parameters lack schema descriptions, so the description must compensate — and it does, explaining include_feat (drops FEAT nodes and touching edges) and title (overrides default 'Reference Graph', sanitized not truncated). This adds real meaning beyond the bare schema. Minor deduction because defaults are stated for title but include_feat's default is left implicit in prose.

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?

Specific verb (Render and return) plus a precisely scoped resource (the whole reference registry, all 13 domains) and output format (PlantUML source). Clearly distinguished from the sibling get_reference_diagram, which operates on a narrower scope.

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?

Tells the agent what to do with the result — 'run it through specmgr plantuml-check (CLI) or the validate_plantuml tool' — which is a real next-step routing. However, it doesn't explicitly state when to prefer this registry-wide variant over the narrower get_reference_diagram sibling, beyond the implied scope difference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses parsing failure behavior (returns ParseFailureResult rather than raising), invalid id raising ValueError before file access, offset/limit clamping semantics, and the error text being byte-identical to the list tool's failed-row error. It does not describe authentication, rate limits, or output schema details, but output schema exists.

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

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

The description is dense but front-loads the core purpose, then layers optional behavior in a logical order. It is longer than ideal, with some redundancy around raw=True semantics and numbered output warnings, but each sentence adds distinct information that an agent needs to invoke correctly.

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

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

Given 5 parameters, 0% schema coverage, no annotations, but an existing output schema, the description covers input semantics, failure modes, constraint interactions, and downstream tool contract warnings. It is complete enough for correct invocation without needing to inspect the schema or other tools.

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%, so the description must fully compensate. It documents raw (frontmatter-stripped body verbatim), offset (1-based, default 1, first body line), limit (line count, default through end), numbered (prefixes lines with absolute body-line number, meaningful only with raw=True), and the coordinate constraints that raise ValueError.

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

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

The description opens with a specific verb+resource: 'Read, parse, and return a full requirement document (frontmatter and body) by its id.' It immediately distinguishes itself from siblings like get_req_template or parse_req by stating what it returns and how raw mode changes behavior.

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

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

Explicitly states when to use raw=True vs raw=False, when offset/limit apply, when numbered applies, and what combinations raise ValueError. Names the downstream tools (update, create_req, edit) that must not receive numbered output, giving clear when-not-to-use guidance.

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

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

With no annotations, the description carries the full disclosure burden, and it does say the output is raw markdown containing both frontmatter and body, and that the sample exercises every section. That is genuinely useful context, but for a parameterless static fetch there is little more to disclose (no auth, pagination, or side effects are mentioned, and none are implied by "Return").

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 dense sentence with the return format front-loaded ("raw markdown") and the purpose trailing. No filler or redundancy, though the em-dash aside slightly loosens an otherwise tight line.

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

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

An output schema exists, so the description need not enumerate return contents, and with no parameters and no annotations there are few behavioral facts to cover. It supplies the format and the sample-completeness guarantee, leaving only sibling routing unaddressed.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description cannot add parameter meaning. Baseline 4 applies for a parameterless definition.

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

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

The description uses a concrete verb ("Return") and a specific resource ("sample requirement document"), and the phrase "for use as a learning example" separates it from near-name siblings like get_req_template and get_req. It stops short of naming those alternatives explicitly, so an agent must infer the distinction from the name.

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?

"For use as a learning example" hints at the intended situation, but the description never states when to pick this over get_req, get_req_template, or the parallel *_example tools, and lists no exclusions. Usage is implied rather than guided.

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, and it does disclose the shape and nature of the output: raw markdown containing frontmatter plus every body field, populated with placeholder content. It implies a read-only, non-mutating operation (Return), though it never explicitly confirms absence of side effects or auth needs, leaving a small gap.

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

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

A single well-formed sentence that front-loads the action and resource, with the useful clarification about placeholder ('blind text') content embedded compactly. No filler and nothing redundant.

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

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

For a zero-parameter read-only template tool with an output schema present, the description covers what is returned, in what format (raw markdown), and the intended use. An agent has everything needed to select and call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments to explain and the description correctly says nothing misleading about 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?

Specific verb (Return) plus a precise resource (a REQ document template) and an explicit statement of what the content is (frontmatter + every body field with placeholder text). An agent can immediately distinguish it from the sibling get_req_example and get_req without opening either.

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?

States the use case clearly: 'for use as a starting point when drafting a new requirement,' which tells the agent when to reach for this tool. It does not explicitly name the alternative (get_req_example) or state when-not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden and does so unusually well: parse failures return a ParseFailureResult (with error/path/id fields) rather than raising, its error text is byte-identical to list's failed-row error, invalid ids raise ValueError before any file access, out-of-range offset clamps to empty string, and offset/limit/numbered combined with raw=False raise ValueError. These are exactly the failure-mode and constraint disclosures an agent needs.

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

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

The purpose is front-loaded in sentence one and every clause is substantive, but the heavy em-dash/parenthetical nesting (e.g. the ADR reference and the nested numbered-output warning) makes it dense to parse. It is long yet largely justified by the tool's genuine complexity.

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

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

For a 5-parameter read tool with a full output schema, the definition covers the input contract, error paths, clamping, and cross-tool interactions (update, create_rsk, edit) completely. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must define all five parameters, and it does: raw toggles frontmatter stripping, offset is 1-based with default 1, limit defaults through end of body, numbered prefixes '<n>: ' with non-restarting absolute numbers. The only gap is that `id`'s expected format is left as 'wrong format' without a concrete example.

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 first sentence states a precise verb+resource+scope: 'Read, parse, and return a full risk document (frontmatter and body) by its id.' This clearly separates it from siblings like get_rsk_template (template), list_rsk (enumeration), parse_rsk (validation) and create_rsk (mutation).

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

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

It gives explicit conditions for each mode: use raw=True for the frontmatter-stripped body, offset/limit only make sense with raw=True, numbered only with raw=True. It even explains how numbered output round-trips into the generic `update` tool. However, it never names an alternative tool for the non-raw case (e.g. parse_rsk for validation or get_rsk_template for the skeleton), so sibling routing is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: it is a read-only retrieval returning raw markdown with frontmatter and body, complete and valid, covering every section. It does not discuss auth, caching, or whether the sample is static, but for a zero-arg example fetch that is a minor gap.

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

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

A single information-dense sentence, front-loaded with the action and result, with the purpose clause last. 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?

An output schema exists, so return values need not be explained, and there are no parameters to document. The description covers what the example contains and why to fetch it, though it stops short of routing between the sibling example/template/get tools.

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

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

The tool takes no parameters, so the baseline of 4 applies. The empty schema leaves nothing to disambiguate.

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

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

States a specific verb (Return), resource (sample risk document), format (raw markdown), and scope (frontmatter and body, every section). The 'learning example' framing distinguishes it from get_rsk (real document) and get_rsk_template (blank skeleton) without the agent needing to open any schema.

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

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

'for use as a learning example' hints at the intended context, but there is no explicit when-to-use vs when-not guidance and no named alternative (e.g., get_rsk_template for scaffolding, get_rsk for real data). Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format (raw markdown) and the exact content structure (frontmatter, every body field, placeholder text), which is valuable behavioral context. It does not mention read-only status, permissions, or side effects, but for a template retrieval this is a minor omission.

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 sentence, front-loaded with the return action and content, followed by the use case. Every phrase earns its place with no filler.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes them. Given the zero-parameter, read-only nature and the output schema, the description is complete for an agent to call it correctly.

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

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

The tool has zero parameters, so the baseline score of 4 applies per the rules. No parameter semantics are needed or provided.

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

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

States a specific verb ('Return') and resource ('risk document template'), and specifies the exact content type (frontmatter, every body field, placeholder 'blind text') and format (raw markdown). This implicitly distinguishes it from get_rsk (actual risk) and get_rsk_example (example content) among siblings.

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

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

Provides a clear use case: 'for use as a starting point when drafting a new risk.' It does not name alternative tools or state when not to use it, but the context for use is explicit.

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 and does so richly: it documents the ParseFailureResult return shape instead of raising, byte-identical error alignment with the list tool, ValueError on path-injection id before any file access, out-of-range clamping, and the cross-tool contract with update's offset. This is unusually deep behavioral disclosure.

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

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

The content is front-loaded with the core read behavior, but the single dense paragraph runs long and buries operational warnings (numbered output not to be fed back verbatim, list-tool error parity, ADR reference) mid-stream. Much of it earns its place, yet structure suffers from cramming distinct concerns into one wall of text.

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

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

Given five parameters with zero schema documentation, no annotations, and a complex dual-mode contract, the description covers parameter semantics, error behavior, clamping, numbering, and cross-tool usage. The existence of an output schema reduces the need to describe return values, and it covers the exception cases (ParseFailureResult) anyway.

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% and the schema has only bare titles, so the description must compensate entirely. It defines raw, offset (1-based, default 1), limit (line count, default through end), and numbered (1-based absolute numbering, clamped-offset semantics, raw-only) with exact interaction rules and error conditions.

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 chain (read, parse, return) and the resource (a full SOP document by id), and distinguishes the raw=True mode. It does not explicitly differentiate itself from sibling get_sop_example or parse_sop, but the dual-mode behavior is clear.

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

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

Explains when to use raw=True vs raw=False and how offset/limit/numbered interact, and explicitly warns against feeding numbered output back into update/create_sop. Lacks a direct comparison to sibling parse_sop or list_sop, so it stops short of explicit alternatives.

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

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

No annotations are provided, so the description carries the burden, and it does disclose the return shape (raw markdown, frontmatter plus body, complete and valid) and that it is static sample content. Read-only, non-destructive behavior is clearly inferable, though it does not mention any auth or rate-limit characteristics.

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 zero filler; the essential scope (sample, markdown, frontmatter+body, every section) is packed in without redundancy.

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

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

An output schema exists, so return values need not be described, yet the description still characterizes the payload usefully. For a zero-parameter static fetcher with an output schema, the definition is essentially complete; only the template-vs-example routing nuance is absent.

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

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

The tool takes zero parameters, so per the baseline the schema has nothing to document and the description correctly adds no parameter detail. Nothing is missing on this dimension.

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

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

States a specific verb (Return) and resource (a complete, valid sample SOP document) plus its distinguishing trait: it is a filled-in example exercising every section, not the real document. This implicitly separates it from get_sop and get_sop_template, though no sibling is named explicitly.

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

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

"For use as a learning example" gives an implied context for use, but the description never says when to prefer this over get_sop_template or get_sop, nor any exclusions. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: output is raw markdown, frontmatter plus all body fields are included, and content is deliberately placeholder text rather than real data. It says nothing about permissions or limits, but for a zero-parameter, side-effect-free template getter that is a minor gap.

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

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

A single sentence, front-loaded with the return value and its format before the purpose clause. The em-dash parenthetical is dense but each element (frontmatter, body fields, placeholder content, markdown) 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes format and content. For a zero-param, annotation-free tool this is close to complete; the only omission is an explicit pointer to get_sop_example as the contrasting sibling.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema description coverage is listed at 100% but the schema is empty, so no param explanation is required.

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

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

States a specific verb (Return) and resource (SOP document template) and describes the content precisely as 'frontmatter and every body field present, populated with short placeholder ("blind text") content ... as raw markdown.' That implicitly separates it from get_sop_example, but it never names the sibling explicitly, so differentiation requires 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?

'for use as a starting point when drafting a new Standard Operating Procedure' gives a clear use context. It does not, however, name alternatives such as get_sop_example or get_sop, nor state any when-not-to-use condition.

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 does a good job: it explains ParseFailureResult behavior for unparseable documents, ValueError for invalid ids raised before file access, and the fact that numbered read of parse-failing doc returns ParseFailureResult. It lacks detail on permissions/auth or whether the read is safe (read-only implied but not stated).

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

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

The description is front-loaded with core purpose but becomes quite long and dense, with multiple nested clauses and parentheticals. While information-rich, it violates conciseness by packing many behavioral rules into a single paragraph without clear structural separation.

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

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

Given output schema exists, return value explanations aren't strictly necessary, and the description does not need to enumerate return fields. It is fairly complete for a read tool with complex parameter interactions, covering edge cases, error modes, and tool interop. Minor gap: no mention of authentication/permissions or rate limits.

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 and it does thoroughly: raw toggles frontmatter stripping, offset is 1-based first body line (default 1, clamps out-of-range), limit is line count (default through end), numbered prefixes lines with absolute body-line numbers meaningful only with raw=True. It also explains ValueError conditions from incompatible combinations.

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

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

The description states a specific verb and resource: 'Read, parse, and return a full System Requirements Specification document (frontmatter and body) by its id.' This clearly distinguishes get_sysrs from siblings like list_sysrs and parse_sysrs by emphasizing full document retrieval by id.

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

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

The description explains when to use raw=True (to get frontmatter-stripped body text verbatim) and how offset/limit/numbered interact with raw mode. It even describes how numbered output connects to the `update` tool's offset parameter. However, it does not explicitly state when to choose get_sysrs vs. parse_sysrs or list_sysrs.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses the return is raw markdown including frontmatter and body, that the sample is complete and valid, and that it exercises every section. It is implicitly a no-side-effect read, though it never states read-only status or that it takes no inputs.

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?

One front-loaded sentence that states action, format, content, and purpose with no filler. Every clause earns its place.

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

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

An output schema exists, so return-value structure need not be restated, and the description covers the key facts an agent needs (sample document, markdown format, all sections exercised). The only shortfall is the missing contrast with the template/get siblings.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a no-argument fetch and adds no spurious parameter claims.

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?

Specific verb (Return) + resource (a complete sample SYSRS document) plus the output format (raw markdown with frontmatter and body). It never names the obvious alternative get_sysrs_template, so the example-vs-template distinction is only implied by 'exercising every section'.

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 'for use as a learning example' gives implied usage, but there is no explicit when-to-use/when-not guidance and no reference to siblings like get_sysrs_template or get_sysrs. An agent must infer the difference between an example and a template on its own.

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