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: read-only and writes nothing, parse failures surfaced as non-raising 'unparseable' findings, not-found errors raised, ValueErrors raised before any file access, and strict-vs-equal staleness semantics with offset-aware datetimes. It also enumerates what is deliberately not compared.

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 read-only statement and the core action, and every clause carries substantive information. The density is high, though — a long semicolon-chained paragraph covering schema tokens, timestamp comparison and error modes would scan better with light structure.

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 four parameters, no annotations and an output schema, the description covers input constraints, comparison rules, error behavior and the shape of the result categories. An agent has everything needed to call it correctly and interpret failure modes.

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 does: it explains that type is one of twelve enumerated artifacts (with feat/adr excluded), id is shared across languages, language must never be 'en', and source_language defaults to 'en' and is what the variant is compared against.

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

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

Opens with a specific verb and resource: compare a translated language variant with its source document and report structural drift and staleness. No sibling tool performs translation-drift checking, and the description makes the scope unambiguous, including that it is read-only.

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 clearly routes mutation intent elsewhere ('to translate or update a variant use the translate_artifact prompt') and states which document types are rejected (feat and adr) plus the invalid-input conditions. It stops short of an explicit 'use this when you suspect a variant is out of date' framing, but the 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?

With zero annotations, the description carries the full disclosure burden and does well: it states that an id is server-assigned, a filename is derived from the title, input is validated and rendered, and a file is written to the ADR base directory. It omits failure/conflict semantics (e.g. what happens if the derived filename already exists) and permission expectations, so not quite 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?

Two sentences, no wasted words. The action and its side effects are front-loaded, and the non-obvious note about the intentionally absent schema resource is placed second where it reads as a clarification.

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, and the rich nested schema covers field semantics. What remains thin is pre-call guidance on conflicts, required-vs-optional expectations at the call site, and how this differs from the update tools—minor but real gaps for a file-writing mutation.

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 description coverage is 0%, but the description compensates by asserting that the two parameters (frontmatter: AdrFrontmatter, body: AdrBody) are themselves the authoritative ADR structure reference, and the nested $defs carry exhaustive per-field documentation (mandatory vs optional, defaults, rendering). The description adds the key routing insight rather than repeating field rules.

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

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

The description names a specific verb and resource and even enumerates the internal pipeline (assign id, derive filename, validate, render, write to ADR base directory), so the agent knows exactly what a call does. It stops short of explicitly differentiating from the ADR mutation siblings (update_section, update_frontmatter, option_create), which keeps it at 4 rather than 5.

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

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

Usage is only implied: the second sentence tells the agent where the authoritative structure reference lives (the typed frontmatter/body params, not a missing resource), which is a genuine usage instruction. But there is no explicit 'use this when starting a new ADR; use update_section/update_frontmatter to modify an existing one' routing among the many ADR siblings.

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

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

With no annotations, the description carries the full burden and does so thoroughly: content-validation failure yields a non-raising ValidateResult with valid=False and a 300-char-capped errors[].message, nothing is written in that case, and it discloses FileExistsError on existing variants, DecNotFoundError for a missing source, and ValueError for malformed language/missing id/extra id before any file access. It also states precisely what is persisted (content verbatim) and that variants start as status draft.

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 opening sentence is front-loaded and efficient, but the body is one dense paragraph laced with internal traceability noise ('feat-110', 'ADR f14f125e-...', 'GitHub issue #204 -- case 5 of the ADR 519d1206 ... chain') that gives an agent no actionable signal. The information is valuable but the structure would be far more usable as short labeled sections for the two modes and the error cases.

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 description still usefully notes that only frontmatter is returned and points to get_dec for the body. Modes, id/language interaction, error types, and write targets are all covered; the only shortfall is that the dense prose structure makes the completeness harder to extract than it should be.

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 for all three parameters: content is the body-only validated content whose H1 supplies the filename; id is optional-null for the default language (must be omitted) but required for a translation and must match the existing EN source id; language defaults to 'en' and must be a lowercase ISO 639-1-shaped two-letter code with a packaged heading-mapping table. This goes well 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?

Opens with a specific verb+resource ('Create a new decision') and enumerates the concrete effects: fresh id, filename derived from the body's H1 title, validation, write to the decision base directory. It also distinguishes the two operating modes (flat docs/dec document vs. translation variant) and names the sibling tools for schema/template and post-creation retrieval, so an agent can separate it from create_prb/create_req and from get_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?

Explicitly routes the agent to get_dec_schema for structure and get_dec_template/get_dec_example for authoring samples, and tells it to call get_dec afterward to fetch the full document since only frontmatter is returned. It also states the conditions that select each mode: omit language for a new document, supply a non-'en' code to create a translation of an existing id.

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 thoroughly: it explains caller-chosen vs default id behavior, no max+1 generation, filename derivation from the H1 title, content validation before id/existence guards, non-raising ValidateResult on invalid content, nothing written on failure, and that only frontmatter is returned. These are substantive details beyond the schema.

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

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

The core behavior is front-loaded in the first sentence, but the description is a dense, overlong paragraph with many parenthetical references (ADR UUIDs, GitHub issue numbers, feat-110) that may not help an agent select or invoke the tool. It is informative but not tightly concise.

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

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

Given the high complexity, low schema documentation, absence of annotations, and presence of an output schema, the description is complete enough: it covers creation, id semantics, validation failure behavior, guard ordering, write conditions, and retrieval follow-up. Return value explanation is present even though output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the optional 'id' parameter's caller-chosen behavior and default format, and describes 'content' as submitted body-only content that is validated before writing, adding meaning not present 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 description names a specific verb and resource ('Create a new feature') and immediately explains the core mechanics: id assignment, filename derivation, validation, and writing to the feature base directory. It also distinguishes related siblings such as get_feat_schema, get_feat_template, get_feat_example, and get_feat for retrieval.

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 clearly indicates this is for creating a new feature and points to get_feat_schema, get_feat_template, and get_feat_example for structure and authoring reference, plus get_feat for fetching the full document afterward. It does not explicitly contrast create_feat with edit/update_frontmatter or set_feat_id, so the when-not guidance is slightly incomplete.

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 discharges it: it discloses the non-raising ValidateResult on validation failure, that nothing is written in that case, that existing variants are never overwritten (FileExistsError), that a missing source is GolNotFoundError, that malformed languages are ValueErrors raised before any file access, and that only frontmatter is returned. This is substantially more than annotations would typically 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 content is front-loaded and substantive, but it is delivered as one very long block dense with internal provenance markers ('feat-110', 'ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204 -- case 5 of the ADR 519d1206 ... chain', 'feat-197-i18n') that add no decision-relevant meaning for an agent. Splitting the default-creation and translation-variant behaviors into separate structures would materially improve scannability.

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

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

For a 3-parameter mutation tool with an output schema present, the description covers everything an agent needs: preconditions, failure modes, the translation path, overwrite protection, and an explicit pointer to fetch the body via get_gol since the return is frontmatter-only. Nothing material is left to inference.

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: `language` semantics (default 'en', ISO 639-1 lowercase shape, must have a packaged heading-mapping table), `id` semantics (must be omitted for default language, required and shared for translation variants), and `content` semantics (body-only, validated through the language's heading table, persisted verbatim) are all 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 opening sentence gives a specific verb and resource ('Create a new goal') plus concrete sub-behaviors: fresh id assignment, filename derivation from the body's H1, content validation, and the write target directory. An agent can distinguish this from create_prb/create_req/create_tsk because the description is scoped entirely to goal documents and their base directory.

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

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

Explicit routing is given for related tools: get_gol_schema for the structure reference, get_gol_template/get_gol_example for authoring, and get_gol afterward for the full body. It also states precise when-to-use branches ('omitted/'en'' vs 'a non-default ISO 639-1-shaped code') and the preconditions that select each one.

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 behavioral burden and does so thoroughly: validation failures return a non-raising ValidateResult with no file written, successful calls return only frontmatter, translations require an existing EN source with shared id, and overwrite attempts raise FileExistsError. It also specifies PrbNotFoundError and pre-file-access ValueError conditions.

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 and logically ordered, but it is a dense single paragraph with implementation references such as feat numbers, ADR UUIDs, and GitHub issue identifiers that do not help an agent invoke the tool. The validation-error explanation is also repeated with excessive internal detail.

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 complex creation tool with no annotations and an output schema, the description covers the important gaps: return shape, validation behavior, translation workflow, file paths, id assignment, and error cases. An agent has enough information to call it correctly in both default and translation modes.

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 define all three parameters, and it does: content is body-only validated content with an H1 title, id is optional for default EN documents but required for translation variants, and language defaults to 'en' with detailed translation semantics. This adds substantial meaning beyond the bare schema.

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

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

The description states a specific verb and resource: creating a new Problem Statement, including id assignment, filename derivation, validation, and persistence. It clearly distinguishes itself from get_prb, get_prb_schema, get_prb_template, and get_prb_example by naming those alternatives and their roles.

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 strong usage context: use get_prb_schema for structure, get_prb_template/example for authoring, and get_prb afterward to fetch the full body. It also explains the default versus translation-mode conditions for the language parameter, though it does not explicitly state when not to create a new problem statement.

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 burden: it discloses that validation failures return a non-raising ValidateResult with nothing written, that existing language variants are never overwritten (FileExistsError), that missing/non-existent sources raise QaNotFoundError, and that malformed language or id mismatches raise ValueError before file access. It also states the return is 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?

Purpose is front-loaded and the content is accurate, but it is a single dense block studded with internal references (feat-110, ADR UUIDs, GitHub issue #204, feat-197-i18n) that add noise for an agent selecting a tool. Bullet-pointing the language branches and dropping ticket/ADR identifiers would improve scannability without losing substance.

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 three parameters, a mutation, an exotic language/translation branch, and an output schema, the description covers everything an agent needs: creation effects, error semantics, no-overwrite behavior, what is returned (frontmatter only), and where to go for the full document and schema. Nothing critical is omitted.

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: 'content' is body-only and validated per-language; 'id' must be omitted for default language but is required (shared EN source id) for a translation; 'language' defaults to 'en' and otherwise must be an ISO 639-1 lowercase two-letter code with a packaged heading-mapping table. This adds substantial meaning absent from the bare schema.

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

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

Opens with a specific verb+resource ('Create a new Question and Answer (QA) document') and enumerates the concrete effects: fresh id, filename derived from H1, body-only validation, write to QA base directory. It explicitly distinguishes itself from get_qa (fetch full document) and points to get_qa_schema/template/example, so an agent can separate it from the many sibling create_* 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?

Explicit routing is given: use this to create, then use get_qa to read the full document; use get_qa_schema for structure and get_qa_template/example for authoring. It also states the precise when-to-use branch for language (omitted/'en' vs non-default code creating a translation of an existing doc), including prerequisites like the EN source having to exist.

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 behavioral burden and does so thoroughly: the non-raising ValidateResult path (valid=False, one errors[].message capped at 300 chars), the guarantee that nothing is written on validation failure, FileExistsError for existing variants, ReqNotFoundError for a missing EN source, and ValueError raised before any file access for malformed input. It also discloses the partial 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?

The core action is front-loaded in the first clause, which is good, but the remainder is a single dense block punctuated by internal identifiers (feat-110, feat-197-i18n, ADR UUID f14f125e..., GitHub issue #204, ADR 519d1206 case 5) that add noise an invoking agent cannot act on. The behavioral facts are valuable; the provenance citations and nested parentheticals make it harder to scan than necessary.

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

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

For a 3-parameter mutation tool with an output schema and no annotations, this covers everything an agent needs: preconditions, error taxonomy, whether files are written or overwritten, the translation-mode branch, and confirmation that only frontmatter is returned with a pointer to get_req for the body. Nothing material is left for the caller to infer.

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: `language` is defined as a lowercase ISO 639-1-shaped code defaulting to 'en' with a large behavioral fork (flat docs/req/ vs docs/req/{language}/ translation with status draft), `id` is described as either forbidden or required depending on that fork and as shared with the EN source, and `content` is described as body-only content validated against the language's heading-mapping table and persisted verbatim. This adds meaning well beyond bare type declarations.

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

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

Opens with a specific verb and resource ('Create a new requirement') and immediately enumerates the concrete side effects: fresh id assignment, filename derivation from the body H1, validation, and write to the requirement base directory. It also names sibling tools (get_req_schema, get_req_template, get_req) that serve adjacent purposes, so an agent can distinguish it from list_req/parse_req/validate 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?

States explicitly what to do afterward ('use the corresponding get_req tool to fetch the full document') and where to get structure guidance (get_req_schema vs get_req_template/get_req_example). It also gives conditional routing rules: omit `id` with default language, supply `id` only when creating a translation in a non-default language. Exclusions and required preconditions are spelled out rather than 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 zero annotations, the description carries the full burden and does so thoroughly: it discloses the non-raising ValidateResult on content failure, that nothing is written in that case, FileExistsError on an existing language variant, RskNotFoundError for a missing EN source, and ValueError for malformed language/missing id/id-supplied-for-default — all before any file access. It also states the return shape is frontmatter only.

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 a genuinely useful first sentence, but the single dense paragraph is polluted by references that mean nothing to an agent — ADR UUIDs, `feat-110`, `feat-197-i18n`, GitHub issue #204, case 5 of an ADR workaround chain. The translation branch would be far clearer as a short list rather than nested parentheticals.

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 a non-obvious dual mode (create vs. translate), three undocumented-in-schema parameters, and no annotations, the description covers creation, validation, error paths, file placement, overwrite policy, and return shape. Since an output schema exists, it does not need to enumerate return fields, and correctly limits itself to noting frontmatter-only.

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: `language` is explained as an ISO 639-1-shaped lowercase code that toggles between fresh-document and translation semantics, `id` is explained as required-for-translation / forbidden-for-default, and `content` is described as body-only content validated against a per-language heading-mapping table. Minor gaps remain (exact accepted shape of `id`, what "body-only" permits regarding an H1) but the meaning added far exceeds the bare schema.

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

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

States a specific verb+resource ("Create a new risk") and immediately enumerates the concrete side effects: fresh id assignment, filename derivation from the body H1, body validation, and writing to the risk base directory. It also contrasts itself with the read/authoring siblings (get_rsk, get_rsk_schema, get_rsk_template, get_rsk_example), so an agent can distinguish write-vs-read 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?

Explicitly routes the agent to get_rsk_schema for structure, get_rsk_template/get_rsk_example for authoring, and get_rsk afterward to retrieve the full document — clear alternative-tool guidance. What it lacks is any statement of when *not* to call it (e.g. to modify an existing risk, use edit/update_frontmatter instead), even though `update`/`edit`/`update_section` are siblings.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses id assignment, filename derivation, validation failure behavior (non-raising ValidateResult, no write), translation-mode file paths, overwrite protection for variants, and specific error classes such as FileExistsError, SopNotFoundError, and ValueError.

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 key behavior are front-loaded, but the description is a single dense paragraph with internal ADR UUIDs, issue numbers, and feature tags that add little for an invoking agent. The complexity justifies substantial detail, but the structure could be clearer and some references 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?

Given the tool's complexity, lack of annotations, 0% schema description coverage, and the presence of an output schema, the description is complete. It explains both default creation and translation modes, validation outcomes, write behavior, error conditions, and what is returned, leaving no major invocation question unanswered.

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 explain the parameters, and it does: content is body-only content whose H1 title drives the filename; id is optional for default English creation but required for translation mode; language defaults to 'en' and switches to translation behavior when set to a supported non-default two-letter code.

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: 'Create a new Standard Operating Procedure.' It then enumerates the concrete actions (assigns a fresh id, derives a filename from the H1 title, validates body-only content, writes the document) and names related SOP tools, so an agent can distinguish it from get_sop, edit, update, and the create_* tools for other document 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?

It gives clear operational context: use get_sop_schema for the structure reference, get_sop_template/get_sop_example for authoring aids, and get_sop afterward to fetch the full document. It also explains when the language parameter switches to translation mode and when id must be omitted or required, though it does not explicitly say to use edit/update rather than create_sop for existing SOPs.

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 that validation failures return a non-raising ValidateResult with nothing written, that an existing variant is never overwritten (FileExistsError), that a missing EN source raises SysrsNotFoundError, and that malformed arguments raise ValueError before any file access. It also notes new variants get status draft and are written verbatim.

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

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

Front-loaded with the core action, which is good, but it devolves into a single dense run-on paragraph salted with internal references (feat-110, ADR f14f125e-..., GitHub issue #204, 'case 5 of the ADR 519d1206 ... chain') that add no decision value for an agent. The same content could be roughly half the length with bulleted mode descriptions.

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 an i18n branch, several failure modes, and a partial-return contract, the description covers creation, translation, validation, persistence, and error behavior. An output schema exists and the description still usefully notes the return is frontmatter only, so an agent knows to call get_sysrs for the body.

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 supply all meaning, and it does: `id` is required only for non-default languages and must be omitted for 'en'; `language` defaults to 'en', must be an ISO 639-1-shaped lowercase two-letter code with a packaged heading-mapping table; `content` is body-only and validated through the language-specific heading table. This is well beyond what the bare schema conveys.

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 System Requirements Specification") and immediately enumerates the concrete side effects: fresh id assignment, filename derived from the body's H1, body-only validation, and write to the sysrs base directory. This cleanly separates it from the many sibling create_* tools for other document 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 routes the agent to companions: get_sysrs_schema for structure, get_sysrs_template/get_sysrs_example for authoring aids, and get_sysrs afterward for the full body. It also spells out the two mutually exclusive usage modes for `language` (default vs. translation of an existing id). It stops short of stating when *not* to use this tool (e.g., use `update`/`edit` to modify an existing spec), which keeps it from 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: validation failures return a non-raising ValidateResult with nothing written, only frontmatter is returned, translation variants are never overwritten, and TskNotFoundError/FileExistsError/ValueError cases are disclosed.

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

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

The purpose is front-loaded and most of the content is relevant, but the single dense paragraph contains internal traceability noise such as long ADR UUIDs, issue #204, and feat tags. The complexity justifies substantial length, but tighter structure and removal of internal references would improve 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?

Given the lack of annotations, three parameters, translation-mode branching, and an existing output schema, the description covers creation, validation, persistence location, return shape, and error outcomes. No material invocation detail appears to be 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?

With schema description coverage at 0%, the description fully compensates by defining all three parameters: content is body-only validated content with an H1-derived filename; id is optional for default creation but required as the shared source id for translations; language defaults to 'en' and selects translation behavior with heading mapping.

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 'Create a new task list' and specifies id assignment, filename derivation from the body's H1 title, body validation, and writing to the task list base directory. The resource is unambiguous against sibling create tools such as create_prb and create_req.

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 structure consultation to get_tsk_schema/get_tsk_template/get_tsk_example and full document retrieval to get_tsk. It also distinguishes default creation (language omitted or 'en', id omitted) from translation mode (non-default language, existing id required) and describes the error conditions that select each path.

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 so thoroughly: it discloses the non-raising ValidateResult on validation failure (valid=False, single errors[].message capped at 300 chars) and that nothing is written in that case, the exact error types (TxtNotFoundError, FileExistsError, ValueError raised before any file access), and that an existing variant is never overwritten. It also states the return shape (frontmatter only, no body) and the on-disk path for translation variants.

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 one very long paragraph dense with internal provenance citations (feat-110, ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204, ADR 519d1206 workaround chain, feat-197-i18n) that add no decision-relevant meaning for an agent. Splitting the two modes and the error contract into separate sentences would materially improve 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?

For a three-parameter mutation tool with no annotations, the description covers every decision point: mode selection, id requirements per mode, validation and failure semantics, error types, file placement, overwrite protection, and the fact that only frontmatter is returned (with an output schema present, no further return-value detail is needed).

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' is explained as the required shared id of the EN source for a non-default language and as forbidden for the default language, 'language' is constrained to a lowercase ISO 639-1-shaped two-letter code with 'en' as default, and 'content' is described as body-only, validated against the language's heading-mapping table, and persisted verbatim.

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 clause gives a specific verb and resource ("Create a new free-form text document") and immediately enumerates the concrete effects: fresh id assignment, filename derived from the H1 title, validation of body-only content, and write to the free-form text base directory. It is clearly distinguishable from siblings like create_prb/create_req and from the read-side get_txt family.

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 routes the agent to the right companion tools (get_txt_schema for structure, get_txt_template/get_txt_example for authoring, get_txt to fetch the full body afterward) and draws an explicit line between the two modes: omit 'language' for a new document, pass a two-letter code to create a translation. What is missing is any when-not-to-use guidance versus the many other create_* tools and versus 'edit'/'update' when the intent is to modify rather than create.

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: validation failures return a non-raising ValidateResult (valid=False, nothing written), return value is frontmatter-only, missing source raises UcNotFoundError, existing variant raises FileExistsError, and malformed/mismatched language or id raises ValueError before any file access. That is exactly the safety and failure-mode context an agent needs before a mutation.

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

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

The operation is front-loaded in the first sentence, but the text is a single dense block bloated with internal process artifacts (ADR UUIDs, 'GitHub issue #204 -- case 5 of the ADR 519d1206 non-raising-structured-result workaround chain', 'feat-110', 'feat-197-i18n') that add no decision value for an agent. The substantive language/id rules are useful but could be trimmed and structured into bullets for faster parsing.

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

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

For a 3-parameter mutation tool with no annotations, the description covers inputs, validation semantics, all error conditions, side effects on disk paths, and return shape (frontmatter only, with an output schema present so body details are rightly deferred). 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 description coverage is 0%, so the description must compensate and it does: `content` is body-only, validated and persisted verbatim (and validated against the language's heading-mapping table for translations); `id` is the shared EN source id, required for non-default languages and forbidden for 'en'; `language` defaults to 'en', must be an ISO 639-1-shaped lowercase code, and requires a packaged heading-mapping table. All three parameters gain meaning not present in the bare schema.

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

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

Opening sentence names a specific verb (create), the resource (use case document), and the concrete effects: fresh id, filename derived from H1, body validated, written to the use-case base directory. It also distinguishes the dual mode (new EN doc vs. translation) and points to get_uc for retrieval, so an agent can separate it from get_uc / create_* siblings without opening a 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?

Clear routing guidance: get_uc_schema for structure, get_uc_template/get_uc_example for authoring inputs, get_uc afterward for the full body. The language/id coupling is spelled out explicitly (omit id for 'en', id required otherwise). However, it never states when to use this versus the sibling edit/update tools for an existing use case, so a modification-vs-creation decision is left implicit.

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

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

With no annotations supplied, the description carries the full burden and does so richly: validation failure returns a non-raising ValidateResult with valid=False and errors[].message capped at 300 chars and writes nothing; malformed language, missing/forbidden id, or absent heading-mapping table raise ValueError before any file access; an existing variant raises FileExistsError; a missing EN source raises VcrNotFoundError. It also discloses that translations get status draft, that content is persisted verbatim, 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?

The core purpose is front-loaded, but the body is a single dense paragraph salted with internal identifiers (feat-110, ADR f14f125e-eaad-..., GitHub issue #204, case 5 of ADR 519d1206) that add noise rather than invocation value. The parameter branching deserves the length, but the ticket/ADR references and nested parentheticals 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 3-parameter creation tool with branching language behavior, the description is complete: it covers what is written, what is returned, error conditions, overwrite protection, and where related tools fit. An output schema exists, and the description still usefully notes that only frontmatter is returned.

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 entirely, and it does: it documents `language` (default 'en', ISO 639-1-shaped two-letter code, selects a heading-mapping table), `id` (must be omitted for default language, required as the shared EN source id for translations), and `content` (validated against the language's heading table, persisted verbatim). This goes well 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?

The opening sentence gives a specific verb + resource ("Create a new verification case record") and enumerates the concrete steps: assigns a fresh id, derives filename from the body's H1 title, validates content, and writes to the base directory. It further distinguishes itself from siblings by naming get_vcr_schema, get_vcr_template, get_vcr_example, and get_vcr with their respective roles.

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 clearly routes the agent: use get_vcr_schema for the structure reference, get_vcr_template/get_vcr_example for authoring, and get_vcr afterward to fetch the full body since only frontmatter is returned. It also spells out the two mutually exclusive branches (default vs non-default language, with id required/omitted accordingly). It does not explicitly compare against edit/update for modifying an existing record, leaving that to inference.

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

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

With no annotations, the description carries the full burden and does so: it discloses permanence, that a domain lock is taken, that a single file vs an entire folder (`feat`) is removed, the language-variant scoping (only that variant file, EN untouched), and the exact error taxonomy (ValueError before file access, XNotFoundError, DeleteError). This is unusually rich behavioral context for a destructive 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?

Front-loaded with the core action, then organized into resolution, deletion mechanics, and error/language behavior. It is long and the language paragraph is dense, but nearly every clause adds decision-relevant information; a slight trim would sharpen 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?

Given a destructive, unannotated 3-parameter tool, the description covers mechanics, scope, return value, and failure modes thoroughly. The note that it 'Returns the deleted path as a string' mildly duplicates the output schema but is harmless, and nothing an agent needs to call it safely 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 description fully compensates: it explains `id` resolution and its invalid-format/path-injection failure, expands on the `type` enum including the `adr` exclusion and `feat`'s folder semantics, and gives precise meaning for `language` (default 'en', ISO 639-1 lowercase shape, per-language subdirectory, malformed or unsupported code raises 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?

States a specific verb and resource ('Permanently delete an existing document from disk'), enumerates the valid `type` values, and explicitly excludes `adr`. An agent can distinguish this from create_*/get_*/edit/update 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?

Explicitly declares itself 'the sole delete entry point -- the former per-domain `delete_<d>` tools are removed', which routes the agent away from nonexistent alternatives. It lacks an explicit statement of when deletion is inappropriate versus e.g. `edit` or `set_status`, so it falls short of full when/when-not 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 exist, so the description carries the full burden and does: two-stage execution, atomicity ("nothing is written on any failure (the file stays byte-unchanged)"), byte-exact matching with no line-ending/BOM/fuzzy fallback, and which failures raise versus return structured results (`ParseFailureResult`, non-raising `ValidateResult`). Return-shape behavior (frontmatter only, no body, `updated` bumped) is also disclosed.

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

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

It is front-loaded with the strongest sentence, but the remainder is one massive run-on paragraph dense with internal references (ADR UUIDs, GitHub issue #170, ADR chain citations) that do not help an agent select or invoke the tool. Length and embedding of critical facts mid-paragraph (e.g. the `language` scope rules) make it hard to scan.

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 six-parameter mutation tool with no annotations, everything an agent needs is present: preconditions, matching semantics, failure modes and their exact result shapes, atomicity guarantee, return value, and language-variant scoping. With an output schema present, it correctly does not re-describe the success payload beyond noting no body is returned.

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 description fully compensates for all six parameters: `old_str` (byte-exact, must be unique unless `replace_all`), `new_str` (empty = pure deletion, legal only if stage 2 validates), `replace_all`, `id` (invalid shape/path injection = pre-dispatch `ValueError`), `type` (`adr` unsupported, enum-consistent), and `language` (default 'en' = flat file, non-default = docs/<type>/{language}/ only, `feat` raises). No parameter is left undocumented.

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

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

"Surgical, exact-match string replacement of an existing document's frontmatter-stripped body" names a specific verb (replace), the resource (document body), and the exact matching contract. The scope restriction ('body only', frontmatter never addressable) and the explicit contrast with `update` lets an agent distinguish it from the ~100 siblings without opening a 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 between siblings: "Use `edit` for a surgical string replacement within an existing body; use the generic `update` tool for a whole-body or line-range replacement instead." It also states the read-before-edit convention and flags that it is a client convention, not server-enforced, plus the `adr` exclusion which tells the agent when this tool is unavailable.

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 fallback returning {available: false, reason, message} instead of raising, the exact error taxonomy (ValueError before filesystem access vs the domain's XNotFoundError), and how unparseable candidates appear (id = null, '<failed to parse>' marker).

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 and every clause carries information, but it is delivered as one dense block mixing defaults, failure modes, and error types; light structuring would improve scanability 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 5-parameter read tool with an output schema, the description covers selection criteria, defaults, ranking, exclusion rules, and failure behavior. The return-row description ({type, id, title, status, path, score}) is technically redundant with the output schema but harmless and aids comprehension.

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: top_k default 10 with validation range 1..100, min_score as an inclusive cosine lower bound defaulting to no filter, target_types as an optional restriction, and type/id as the source document identifier. It also clarifies that adr is unreachable via type, information absent from the enum documentation.

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 ('find') and resource ('documents most semantically related to an existing document') plus the mechanism (cosine similarity of local embeddings). The 'given its type/id' framing distinguishes it from query-text-based tools like find_similar_text, so an agent can route correctly 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?

Explains the default search scope (all whole-body domains, adr structurally excluded), how to narrow it via target_types, and that the source document is excluded. It does not explicitly name an alternative tool (e.g. find_similar_text) or state when to prefer it, which keeps this short of a 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: default domain coverage with adr structurally excluded, ranking and sort order, top_k range validation, min_score as an inclusive cosine bound, degraded-mode behavior ({available:false, reason, message}) when embeddings are unavailable, and that invalid args raise ValueError before any filesystem access. This is unusually complete behavioral disclosure for a read tool.

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

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

Purpose and scope are front-loaded before the mechanics, and every clause carries information. It is still a single dense paragraph with heavy parenthetical nesting, which costs some scannability against an ideal structured layout.

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 4-parameter read tool with an output schema, the definition covers invocation semantics, ranking, filtering, edge-case rows (id=null for unparseable candidates) and failure modes. Even the return-row shape is summarized, leaving no gap an agent would need before calling 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: it defines query as free-form text, top_k's default 10 and validated 1..100 range, min_score's default (no filter) and inclusive lower-bound meaning, and target_types' restriction role against the full default domain list. Every parameter gains meaning beyond the bare schema.

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

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

States a specific verb (find) and resource (documents most semantically similar to a free-form query), plus the mechanism (cosine similarity of local sentence embeddings) and the intended purpose (pre-creation dedup/discovery). An agent can distinguish this semantic-similarity search from keyword/metadata lookups like list_* or get_* 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 scopes usage to 'pre-creation dedup/discovery checks', which tells the agent when this tool is the right choice. It does not name a specific alternative (e.g. find_related) or state when-not to use it, so it falls short of the top band.

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 a useful behavioral trait: an invalid id raises ValueError before any file access, which signals input validation ordering. It does not say what happens when a well-formed id matches no existing ADR (missing file vs. empty result), nor does it explicitly confirm the operation is a pure read with no side effects.

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

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

Two sentences, the core action front-loaded in the first, with the error-path caveat second. Every clause adds information 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 shape need not be explained. For a single-parameter read tool without annotations, the remaining gap is the not-found case and the id format, which an agent needs in order to call it correctly the first time.

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 only partially does: it establishes that 'id' identifies an ADR document and that malformed or path-injection ids are rejected. It never states the expected id format (e.g., ADR-001 style), which is exactly what the undocumented parameter leaves ambiguous.

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 set and resource: 'Read, parse, and return a full ADR document (frontmatter and body) by its id.' This clearly separates it from list_adr (enumeration). It does not, however, distinguish itself from the sibling parse_adr, leaving the reader to guess how 'get' and 'parse' differ.

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

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

There is no guidance on when to call this instead of list_adr, parse_adr, or validate_adr. The only conditional statement concerns invalid ids, not tool selection, so an agent gets no routing help.

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: language variants are shape-validated before any file access, missing heading tables are rejected up front with actionable ValueErrors, parse failures return a ParseFailureResult rather than raising, and out-of-range offset/limit clamp to an empty string. It even documents cross-tool invariants (error text byte-identical to list_dec, numbered output must be stripped before feeding update/create_dec/edit).

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 purpose is front-loaded, but the body is a single ~330-word paragraph of chained em-dashes and parentheticals that is hard to scan. Some content is repeated ('before any file access' appears twice) and the ADR hash reference is noise for an invoking agent, though the underlying behavioral facts do 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?

For a 6-parameter, 0%-schema-coverage, unannotated tool this is close to complete: modes, validation ordering, error shapes, clamping, and cross-tool constraints are all covered, and the existing output schema relieves it of explaining return values. The only substantive omission is the accepted format of `id`.

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 supply all parameter meaning, and it does for language (default 'en', docs/dec vs docs/dec/{language}/), raw, offset (1-based, default 1), limit (default through end), and numbered ("<n>: " prefix, absolute numbering that survives windowing). The required `id` parameter gets only error behavior (path-injection/wrong format → ValueError) but never states the expected id format, leaving one 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?

Opens with a precise verb+resource+scope: 'Read, parse, and return a full decision document (frontmatter and body) by its id.' It also makes the boundary against related tools explicit by naming list_dec, update, create_dec and edit and describing how their outputs/inputs interact with this tool's.

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 clear conditional guidance for the main modes: use raw=True for verbatim body text, raw=False for the parsed structured model, and offset/limit/numbered only with raw=True (with the stated ValueError otherwise). It never states the plain 'use this instead of list_dec when you know the id' routing rule, so the sibling-selection guidance 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 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 provided, the description carries the behavioral burden and does add useful context: the schema is generated by `specmgr schema`, kept current by a pre-commit hook/CI step, and includes a `$comment` version marker for detecting shape changes. It does not explicitly state that the operation is read-only or describe failure behavior if the schema is unavailable, but the core behavioral traits are 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?

The description is front-loaded with the return type and dialect, then gives usage guidance and generation details. It is somewhat long but every sentence carries useful information -- return format, alternative, usage conditions, and freshness marker. It could be tightened slightly, but it does not waste space on restating schema fields.

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 in detail. It covers purpose, alternatives, usage conditions, and the freshness/version-marker behavior. For a zero-parameter schema retrieval tool, nothing important is missing 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?

The tool has zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description appropriately does not invent parameter details. The empty input schema is consistent with the description.

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

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

The description gives a specific verb-resource pair: it returns the DEC domain's generated JSON Schema in 2020-12 dialect as raw text. It also distinguishes this from the markdown/template view by naming `get_dec_template` as the alternative for authoring. An agent can tell exactly what this tool produces versus its 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 explicitly names when to fetch it: constraint discovery, structural questions, or unresolved validation errors. It also gives a negative instruction -- never as a mandatory pre-authoring fetch -- and points to `get_dec_template` for the authoring starting point. This is clear when/when-not guidance with an explicit alternative.

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, the description carries the full burden and does so: parse failures return a ParseFailureResult instead of raising, invalid ids raise ValueError before file access, out-of-range offset/limit clamp, and incompatible flag combinations raise ValueError. It even discloses the warmup/caching nuance that affects error fidelity relative to list_feat, which is behavior no schema could 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 critical points are front-loaded, but the description is bloated with ADR identifiers and a long, self-referential digression on byte-identity with list_feat's error rows. That parity detail is tangential to calling this tool and inflates the middle of an otherwise efficient definition.

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 five-parameter read tool with an output schema, the description covers the mutation-adjacent edge cases an agent actually needs: failures return a structured result, flag conflicts raise, and numbered output is not round-trippable into write tools. Nothing essential to 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 description coverage is 0%, so the description must compensate and it does: `raw` semantics, `offset` (1-based, default 1), `limit` (default through end of body), clamping behavior, and `numbered` (prefix format, numbering continues from clamped offset, only valid with raw=True). That is meaning well beyond the bare types and defaults 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 gives a specific verb and resource: read, parse, and return a full feature document (frontmatter and body) by id. It immediately distinguishes the raw variant, so an agent knows exactly what it gets without opening the schema.

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

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

It clearly explains the raw=True mode switch and warns against feeding numbered output back into `content` for `update`/`create_feat` or using it as `edit` `old_str`, which is actionable guidance. However, it never says when to prefer this tool over siblings such as `parse_feat`, `list_feat`, or `get_feat_example` for discovery, so the alternative-selection story is implicit.

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

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

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, the description carries the disclosure burden and does well: it explains provenance (`specmgr schema`, pre-commit hook/CI refresh) and that the document includes a `$comment` layout-version marker for detecting shape changes. It omits how the raw text is delivered (size, pagination/truncation) or whether the fetch has side effects, which keeps it below 5.

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

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

Front-loaded with the core action and resource, then the disambiguation and usage rules in priority order. It is a single dense sentence with several parentheticals; nothing is wasted, but the length slightly taxes 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?

Output schema exists, so return-value explanation is unnecessary. Given a zero-parameter, no-annotation tool, the description covers what it is, what it returns, where it comes from, when to call it, when not to, and which sibling to use instead — nothing an agent needs 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?

The tool takes zero parameters, so there are no semantics to disambiguate and the baseline of 4 applies. The description correctly adds no spurious 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 and resource ('Return the FEAT domain's generated JSON Schema ... as raw text') and immediately contrasts it with the markdown view and with `get_feat_template`. An agent can distinguish it from get_feat_template, get_feat_example, and the sibling *_schema tools without opening a 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?

Explicit positive triggers ('constraint discovery, structural questions, or an unresolved validation error') and an explicit prohibition ('never as a mandatory pre-authoring fetch'). It also names the alternative tool to use for authoring start, so the routing decision is fully specified.

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 does so: it discloses that invalid ids and path-injection payloads raise ValueError before any file access, that unparseable documents return a ParseFailureResult rather than raising, that out-of-range offset/limit values clamp, and that mixing offset/limit/numbered with raw=False raises ValueError. It even warns that numbered output is not valid input for update 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 content is valuable but delivered as one unbroken ~400-word block with no paragraphing or bullets, so the default raw=False path is buried behind secondary raw=True windowing details. The byte-identical ParseFailureResult claim (including a full ADR UUID) is stated twice, once in the middle and again in the final sentence, which is 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 6-parameter tool with an output schema and zero annotation coverage, the description covers everything an agent needs: parse-failure shape, error paths, parameter interactions, and language-variant parsing semantics. Nothing material about calling it correctly is left unstated.

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

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

Schema coverage is 0%, yet every non-trivial parameter is fully specified: offset is 1-based with default 1 and clamping behavior, limit defaults to through-end-of-body, numbered emits "<n>: " 1-based absolute line numbers that continue past a windowed offset, and language defaults to 'en' with the flat path versus docs/gol/{language}/ variant rule. This compensates entirely for the empty schema descriptions.

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 concrete verb+resource+scope: "Read, parse, and return a full goal document (frontmatter and body) by its id," and immediately contrasts that with the raw=True body-text mode. An agent can tell this apart from list_gol, parse_gol, and create_gol without opening a schema.

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

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

Gives explicit conditions for the major modes: raw=True for verbatim frontmatter-stripped body, offset/limit only meaningful with raw=True, numbered only with raw=True, and language variants selected via ISO-shaped codes. It never explains when to pick this over the sibling parse_gol tool, which is the one remaining routing ambiguity.

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?

With no annotations, the description does real work: it discloses the output is raw text not rendered markdown, that content is generated by `specmgr schema` and kept current by a pre-commit hook/CI, and that a `$comment` version marker enables shape-change detection. It doesn't discuss permissions or caching, but read-only retrieval is implied and the freshness/source disclosure is well beyond typical.

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 what is returned before the usage guidance and the version-marker detail. It is a single dense paragraph and slightly overstuffed, but each clause (raw text vs markdown, source, freshness, $comment marker) carries distinct information.

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

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

For a zero-parameter read tool with an output schema, the description covers purpose, selection, format, provenance, and freshness, which is everything an agent needs before invoking it. Return-value detail can safely be deferred 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 and there is no parameter semantics to add. The description appropriately spends none of its space restating an empty schema.

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

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

States a specific verb and resource ('Return the GOL domain's generated JSON Schema as raw text') and explicitly disambiguates from the markdown view and from get_gol_template. An agent can distinguish it from the many get_*_schema and get_*_template siblings without opening schemas.

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

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

Gives concrete triggers ('constraint discovery, structural questions, or an unresolved validation error') and an explicit exclusion ('never as a mandatory pre-authoring fetch'), plus names the alternative for authoring. Nothing is left to inference.

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

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

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?

With zero annotations the description carries the full burden and does so richly: it discloses that a broken document returns a ParseFailureResult instead of raising, that invalid ids and path-injection payloads raise ValueError before any file access, that offset/limit clamp out of range, that unsupported language codes are rejected up front, and that raw=True preserves translation while raw=False maps headings to canonical text. It also warns that numbered output must be stripped before reuse in content/old_str, which is exactly the kind of behavioral context annotations would otherwise supply.

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, but the body is a run-on of em-dash-chained clauses that repeats itself: the byte-identical ParseFailureResult error claim appears twice, and the ValueError conditions for offset/limit/numbered are restated. Dense as it is, an agent must parse one very long paragraph to extract the several distinct modes, when short bullets or a mode table would convey the same content far more efficiently.

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 restated, and against that lower bar the description covers error paths, language variants, windowing, and numbered output thoroughly for a 6-parameter tool. The only real gap is the missing distinction from the sibling parse_prb, which occupies the same parse-the-document niche and is never mentioned.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate, and it documents every one: offset is 1-based with default 1, limit defaults to end-of-body, out-of-range values clamp and offset > N yields the empty string, offset/limit/numbered are only valid with raw=True, and language defaults to 'en' mapping to docs/prb/ versus docs/prb/{language}/. It also states that numbered emits a 'n: ' prefix whose numbers start at the clamped offset, which is meaning no schema could convey.

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: 'Read, parse, and return a full problem statement document (frontmatter and body) by its id', and names the sibling behaviors it is not (update, create_prb, edit) when warning about feeding numbered output back. It never distinguishes itself from the equally-named sibling parse_prb or from list_prb beyond error-text parity, so it falls short of full sibling differentiation.

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 clearly says when to use the two modes ('Pass raw=True to return the frontmatter-stripped body text verbatim instead') and when offset/limit/numbered apply, including that they raise ValueError with raw=False. It gives no guidance at the tool level, however: nothing says when to call get_prb versus parse_prb, list_prb, or get_prb_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 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?

With no annotations provided, the description carries the full burden and does so: it discloses the output is raw text rather than parsed objects, the provenance (generated by `specmgr schema`, refreshed by pre-commit hook/CI), and the `$comment` version marker for detecting layout changes. That is meaningful context beyond a bare "get".

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 what is returned, then usage routing, then provenance. Dense but nearly every clause carries information; the CI/pre-commit sentence is slightly more than an agent needs to select 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?

Output schema is present, so return-value detail is not required, and the description covers format, provenance, versioning, and sibling routing. 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond implying no filtering/targeting is needed.

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

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

States a specific verb ("Return") and resource ("PRB domain's generated JSON Schema, 2020-12 dialect, as raw text") and explicitly distinguishes itself from the markdown view and from get_prb_template. An agent can pick this over get_prb_template 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?

Gives positive triggers ("constraint discovery, structural questions, or an unresolved validation error") and a negative one ("never as a mandatory pre-authoring fetch"), plus routes to the sibling get_prb_template for the authoring starting point. Both when and when-not are covered.

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

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

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, the description carries the full burden and does so well: it discloses that parse failures return a ParseFailureResult rather than raising, that invalid ids and incompatible parameter combinations raise ValueError before any file access, and that out-of-range offset/limit clamp. It stops short of explicitly stating the operation is read-only and side-effect free, which would matter more given the absence of 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?

The core behavior is front-loaded correctly in sentence one, but the body is a dense run-on paragraph dense with em-dashes and nested parentheticals. Detail like the ADR UUID, the repeated "byte-identical" guarantees, and the trailing pydantic documentation line note add length without changing how an agent would 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?

For a six-parameter tool with no annotations and a declared output schema, this is complete: failure modes, validation ordering, language-variant resolution, and cross-tool data-flow hazards (never feed numbered output into content or old_str) are all covered. Return-value shape is rightly left 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?

Schema coverage is 0%, so the description must compensate entirely, and it does: every one of the six parameters gets meaning beyond its type — raw's body-only behavior, offset's 1-based default and clamping, limit's through-end default, numbered's "<n>: " format and absolute numbering under windowing, language's flat-vs-subdirectory resolution and shape validation, and id's path-injection rejection.

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

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

Opens with a specific verb and resource: "Read, parse, and return a full QA document (frontmatter and body) by its id," which is immediately actionable. It does not, however, distinguish itself from the sibling parse_qa tool, which an agent would reasonably consider interchangeable given the word "parse" in the description.

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 thoroughly explains the mode-selection logic for raw, offset/limit, numbered, and language, which is genuinely useful usage guidance. But it never routes between siblings: parse_qa is unmentioned, and list_qa/update/create_qa appear only as error-message or data-flow references, not as alternatives with a stated selection 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 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?

With no annotations, the description carries the burden and does well: it discloses the output is raw text (not parsed JSON or markdown), that content is generated by `specmgr schema` and kept current by a pre-commit hook/CI, and that a `$comment` version marker allows shape-change detection. It stops short of stating read-only safety or whether the response is a snapshot versus live generation, 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?

Front-loaded with the core action and what it is not, then the when-to-use clause, then provenance. It is a single dense paragraph with heavy em-dash nesting, which slightly reduces scannability, but every sentence 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?

An output schema exists, so return values need no explanation, and the description still clarifies the raw-text form and version marker. Provenance and anti-pattern guidance are both present; nothing an agent needs to call this 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies the tool takes no scoping arguments by describing the QA domain as the fixed subject.

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

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

States a specific verb and resource (return the QA domain's generated JSON Schema, 2020-12 dialect), and immediately distinguishes the artifact from the markdown view authored via get_qa_template. An agent can tell exactly what this returns versus its many 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?

Gives concrete triggers (constraint discovery, structural questions, unresolved validation error), an explicit exclusion (never a mandatory pre-authoring fetch), and names the alternative tool for the authoring path. This is the when/when-not/alternative pattern done correctly.

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 behavioral burden and does so thoroughly: guard order and which checks raise ValueError before any filesystem access, missing source raising the domain's XNotFoundError, broken source returning the non-raising ParseFailureResult with its error/path/id shape, byte-identical error text guarantees, and the adr exception. It also states the return is PlantUML source, not a specmgr document, and names the validation path.

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?

Information density is high and the primary purpose is front-loaded, but the body is one unbroken paragraph of nested parentheticals with spec citations ('specmgr://reference-graph §2–§5', 'the 2026-10-15 corrected form', ADR hashes) that add bulk without changing how an agent calls the tool. It is sized for the complexity but poorly structured 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 six-parameter render tool with an output schema already present, every decision an agent must make is covered: domain/id format, depth semantics, reverse and include_feat interactions, title override, error taxonomy, and the follow-up validation step. Nothing needed 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 compensate and it does for every parameter: type is given as the source's domain with the enum spelled out, id is the source's own identifier with the feat full-slug-vs-bare-id trap and the list_feat escape hatch, depth is bounded 1..5 with default 1, reverse is described as additive forward-plus-direct-incoming, include_feat defines cascading edge removal, and title defines default and sanitization/no-truncation behavior.

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 precise verb+resource: 'Render and return the deterministic PlantUML component diagram of one source document's reference neighbourhood', and enumerates exactly what the diagram contains (nodes per artifact, per-domain groups, edges, cycle edges, UNRESOLVED nodes). It scopes to 'one document', which implicitly separates it from the get_reference_diagram_all sibling, but never names that sibling or otherwise routes between 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?

Usage context is implied by the scoping ('one source document') and by the closing instruction to run the output through specmgr plantuml-check or validate_plantuml, which is genuinely actionable. However there is no explicit when-to-use/when-not guidance and no comparison to the near-identical get_reference_diagram_all or to list_references, so the agent must infer the choice.

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