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

Annotations only declare readOnlyHint=false, so the description carries nearly the full burden for a mutation tool. It never states whether the check is persisted globally or per-project, what happens on duplicate titles, whether permissions are required, or that fitness_test is what makes the check enforceable in CI.

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

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

Two short sentences, front-loaded with the primary action and immediately followed by the trigger condition. No filler or restated title.

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 seven-parameter mutation with no output schema, the description omits what a successful creation returns (an ID?) and how the optional pattern/fix/fitness_test fields relate to enforcement. The 100% schema coverage compensates for parameter gaps, but the behavioral gap remains.

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

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

Schema coverage is 100%, so all seven parameters including the category and severity enums are documented in the schema; baseline 3 applies. The description's parenthetical hints at the pattern/fix distinction but adds no format or usage detail beyond what the schema already provides.

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

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

Specific verb+resource: "Create a new check in SystemDox", clarified by parenthetical examples (banned pattern, required pattern, coding rule). It does not differentiate from adjacent siblings such as create_guardrail or create_project_rule, which an agent could easily confuse with this.

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?

"Use this when you discover a pattern that should be enforced" gives a clear triggering condition rather than leaving usage implied. There are no exclusions, so it does not say when to prefer create_guardrail or create_project_rule instead, which is the main ambiguity for this tool family.

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?

Annotations only declare readOnlyHint=false, so the description usefully adds lifecycle context the annotations cannot: the tool is deprecated, still functional, and guaranteed to exist until 2027-01-31. It does not say what happens on creation (duplicate handling, validation, whether an ID is returned), which keeps it short of 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?

Three sentences, front-loaded with the deprecation warning so an agent sees the redirect before anything else. Every sentence carries distinct information: deprecation, timeline, action, trigger.

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

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

For a 7-parameter mutation tool with no output schema, the description covers routing and lifecycle well but says nothing about the result of a successful create or any failure modes. Annotations are minimal (only readOnlyHint), so the missing behavioral detail is a real gap, though the fully documented schema offsets much of it.

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 100%, so every one of the 7 parameters is already documented. The description only loosely echoes the field intent with 'banned pattern, required pattern, coding rule,' which maps to pattern/fix without adding format or constraint detail. Baseline 3 applies when the schema does the heavy lifting.

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: 'Create a new check in SystemDox.' It also resolves the naming ambiguity with the sibling create_check by declaring this name a deprecated alias. The only reason it is not a 5 is that 'check' vs the tool name 'guardrail' requires the reader to reconcile two vocabularies.

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 both the positive trigger ('when you discover a pattern that should be enforced') and the negative route ('DEPRECATED — use create_check instead'). An agent knows exactly when to call this and when to call the sibling instead, with no inference required.

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?

Annotations supply only readOnlyHint=false, so the description carries nearly the full disclosure burden. It does not say where the rule is persisted, whether it takes effect immediately or requires approval, whether duplicate rules are rejected, or whether rules are enforced automatically — all material for a write tool in a 'Standards' system.

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

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

Two short sentences, purpose front-loaded, no filler. Slight redundancy between 'project rule' and 'across the project', but nothing wasteful.

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

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

The tool is simple (two required params, no output schema, no nesting), so the description is close to sufficient. It still leaves out the outcome of the call and the relationship to the guardrail/check creation siblings, which matters for correct tool selection.

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 100%, with both parameters documented including enum values for category, so the baseline of 3 applies. The description adds no additional meaning about the parameters (e.g., length limits on text or how to choose between 'process' and 'other').

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+resource ('Create a new project rule') and the target system ('SystemDox Standards'), which is unambiguous. It does not distinguish this from similar siblings such as create_guardrail, create_check, or create_prompt_template, which also create project-scoped artifacts.

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?

'Use this when you discover a team principle or convention that should be enforced across the project' gives a usable trigger condition. However it offers no when-not guidance and does not say how this differs from create_guardrail, the closest-sounding sibling, so an agent could plausibly pick the wrong 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?

Annotations only carry readOnlyHint=false, so the agent already knows this is a write. The description adds no behavioral detail beyond that: nothing about whether template names must be unique, what happens on a name collision, whether 'description' is optional, permissions required, or what the call returns. For a creation tool with no output schema, that leaves real gaps.

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, verb-first and front-loaded, with no filler. The second sentence restates the storage intent at slight length ('preconfigured prompts for common AI tasks') but the concrete examples 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 simple three-parameter create tool with full schema coverage and no output schema, the description covers the what and a hint of the why. It stops short of the things an agent would still wonder about: name uniqueness rules, required vs optional fields, and whether the created template is returned or must be fetched.

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 100%, so all three parameters are already documented in the schema. The description reinforces the intent of 'prompt' as the stored reusable text but adds no new syntax, format, or constraint guidance. Baseline 3 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?

The description names a specific verb and resource ('Create a new reusable prompt template') plus the destination store ('SystemDox Standards'). That is enough to distinguish it from the read-side sibling get_prompt_templates, though it never names that sibling explicitly.

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

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

It gives positive usage context with concrete examples ('code reviews, documentation generation, or analysis frameworks'), which is better than nothing. However, it offers no when-not guidance, no mention of the alternative (get_prompt_templates for reading), and no prerequisites or scope limits.

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?

Annotations already declare readOnlyHint=true, so the trailing 'Read-only.' adds nothing. The one genuinely useful behavioral disclosure is that the data is a snapshot — 'as SystemDox last synced it from GitHub' — which warns about staleness and is not in the annotations. No mention of failure modes (unknown repo/slug) or how large the payload can 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-loads the verb and resource, then the content enumeration, then the actionable directive. The final 'Read-only.' is redundant against readOnlyHint=true, but one redundant clause does not warrant a deduction.

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?

No output schema exists, so the description carries the return-value burden and does so thoroughly: brief parts, ADR and status, contract files, feature files with scenario form, plan artifacts, release PRs, the raw Change JSON, and the terminal pass/fail line. Combined with the gates in the usage sentence, an agent has everything needed to call it and interpret the result.

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 100% and both params are self-documenting, so the baseline is 3. The description does add modest value by tying `slug` to the specs/changes/<slug>/ folder convention and framing `repo` as 'a connected repository', but it repeats rather than extends the schema's owner/name and folder-name notes.

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

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

States a specific verb and resource ('Read one change') and pins the resource to a concrete location, 'a specs/changes/<slug>/ folder of a connected repository'. The subsequent enumeration of what the change contains separates it clearly from siblings like get_specs or get_plan_board, which cover broader scopes.

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 an explicit invocation trigger ('Call it before building a story') plus a hard stopping condition tied to the 'brief is not passed' verdict and unproposed scenarios. It does not name alternative tools or say when NOT to call it relative to get_specs/get_context, which keeps it at 4.

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 full burden. The verb "Retrieve" does disclose that this is a non-mutating read, but the description says nothing about default behavior with zero filters, result volume, ordering, or truncation limits.

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

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

Two short sentences, front-loaded with the resource and followed by the filtering capability; no filler. It could be tightened slightly by making the relationship between the filters (can they combine?) explicit rather than implied.

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 simple, all-optional-parameter read tool with no output schema, the definition covers what is fetched and how to narrow it, which is adequate. It omits the unfiltered default case and any sense of result shape, which are the remaining gaps for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three filters with enumerated example values (and even notes that file_path auto-detects language). The description merely restates the same three filter dimensions, so it adds no meaning beyond the schema — the baseline 3 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?

The description uses a specific verb ("Retrieve") plus a concrete resource (SystemDox checks) and parenthetically defines what a check is (banned patterns, required patterns, coding rules). It does not, however, distinguish this tool from nearby siblings like get_guardrails or get_project_rules, which sound conceptually adjacent.

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 states the three filtering axes (language, category, file path) and the goal of narrowing to relevant checks, which implies usage. It never says when to choose this over get_guardrails / get_project_rules, or what happens if no filter is supplied, leaving the selection decision 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 load and does well: it discloses relevance ranking against the task, a token-budget truncation behavior, that only top-ranked items come back in full text, and that IDs are returned so the remainder can be fetched. It does not say what happens when a single item exceeds the budget or how ties/ordering are resolved, so it stops short of fully predictable behavior.

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

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

The core capability and the token-budget/ID follow-up mechanic are front-loaded in one dense sentence, with the routing rule second. The em-dash aside is efficient, though the opening sentence is long enough that an agent must parse a lot before reaching the 'use instead of' directive.

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 aggregator with no output schema, the description explains the return shape (ranked full text, partial coverage, IDs for the rest) and the budget constraint well enough to call it correctly. What is missing is edge-case behavior around budget exhaustion and whether empty results are possible, which is a modest gap rather than a blocking one.

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 100%, so baseline is 3, but the description adds genuine semantics: task_description drives the relevance ranking (not just a label), and max_tokens is a hard truncation boundary on the response rather than a soft hint. That meaning is absent from the schema's own phrasing.

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 concrete verb (fetches/ranks/returns) and enumerates the resources aggregated: checks, specs, docs, tech stack. It also states the output shape (ranked full text plus IDs) and contrasts itself with the individual sibling tools, so an agent can distinguish it from get_checks, get_specs, get_docs, and get_tech_stack 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?

"Use this instead of calling individual tools when you want curated, relevant context" gives an explicit selection rule against the most likely alternatives. The gap is the inverse case: it never says when to prefer a targeted sibling (e.g., you already know the doc or check ID you need), which matters given eleven sibling get_* tools.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does usefully describe the behavioral distinction between whole-document and single-section retrieval, but says nothing about result ordering, truncation or size limits, pagination, or what an empty result means.

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?

Three sentences, front-loaded with the resource and source, then filtering options, then the narrowing path. No filler or redundancy.

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

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

For a six-parameter, zero-required-parameter read tool with no output schema, the description covers the main retrieval shapes well. The one meaningful gap is the default behavior when no parameters are passed (full listing? bounded result set?), which an agent would need to know.

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 100%, and each parameter already documents its own format (glob example, owner/repo, heading anchor, chunk id format). The description largely restates that the doc_id+section/chunk_id combination narrows results rather than adding new semantics, so it earns baseline credit only.

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+source: "Retrieve synced documentation from connected GitHub repositories," and names the three filtering axes plus the targeted-retrieval mode. It is clearly distinct from most siblings (get_checks, get_specs, get_graph_stats), though it never explicitly contrasts itself with get_context or get_document_links.

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

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

Usage is implied by the enumerated filter options and by the instruction to pass doc_id with section or chunk_id for a single section. There is no explicit when-to-use/when-not guidance, no mention of which sibling to prefer for specs, links, or context retrieval, and no statement of prerequisites.

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?

Annotations only declare readOnlyHint=true, and the description adds substantial behavior beyond that: link provenance tiers (declared/extracted/inferred), a confidence value, source file and line, and the rule that ambiguous references are listed with candidates but never drawn as links. That is real disclosure about what comes back and how much to trust it. The restated 'Read-only' is redundant with the annotation but not contradictory.

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?

Three front-loaded sentences: ordering first, then provenance semantics, then the ambiguity caveat, ending with the read-only note. Dense and mostly earn-its-place, though 'Read-only.' duplicates the readOnlyHint annotation.

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 output schema, the description carries the burden of explaining return values and does so well: each link's provenance, confidence, and file/line origin, plus ambiguous-reference handling. Minor gaps remain around how limit truncation interacts with 'strongest first' and whether relation/direction filtering changes the ordering semantics.

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 100%, so limit, doc_id, relation, and direction are already documented in the schema. The description reinforces doc_id's provenance ('the id get_docs returns') but adds no meaning to the relation enum values or the direction modes, so it matches the baseline for a fully covered 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?

Names a concrete resource and scope: incoming and outgoing links for one document, ordered strongest first. It implicitly separates itself from get_docs by defining doc_id's origin, but never distinguishes itself from trace_document_path or get_graph_stats, so sibling differentiation is only partial.

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

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

Usage is implied through the get_docs reference (call get_docs first to obtain doc_id), which gives a usable workflow hint. There is no explicit when-to-use versus when-not-to-use guidance, and no mention of when to prefer trace_document_path or get_graph_stats instead.

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?

Annotations already declare readOnlyHint=true, so the description's 'Read-only' line is redundant but consistent. It does add real domain behavior beyond the annotations by explaining the BEHIND marker meaning (a push has not finished indexing) and clarifying that link counts are grouped by how relationships are known, which tells the agent how to read the output.

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

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

A single dense sentence front-loads the resource, then lists the three returned facets, ending with a short safety note. Every clause carries information, though the phrasing 'links counted by how they are known' is slightly indirect and the trailing 'Read-only' duplicates the annotation.

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 output schema, the description must convey what comes back, and it does so at a high level for all three output facets, including the meaning of the BEHIND flag. It could say more about scope (single workspace vs all repositories) or output shape, but for a parameterless read-only summary it is largely complete.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the empty schema is self-evident and the description correctly spends no words on arguments.

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

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

The description names a specific resource (the graph) and enumerates what its state covers: link counts by provenance, per-repository freshness with a BEHIND flag, and inter-repository dependencies. An agent can tell this is a graph-level summary rather than a single-repo lookup, though it never explicitly contrasts itself with siblings like get_tech_stack or get_context.

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 mention of freshness and dependency data suggests it is the orientation/overview call before drilling into a repository. There is no statement of when to prefer it over sibling get_* tools, no prerequisites, and no exclusions.

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 full burden. It discloses the important lifecycle trait (deprecated, still functional, removal horizon) and that filtering narrows results, but says nothing about read-only safety, permissions, result size, or whether all checks are returned when unfiltered.

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, nothing wasted, and the most decision-critical fact (deprecation plus replacement) is front-loaded before the functional description.

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

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

For a simple, fully documented zero-required-parameter read tool with no output schema, the definition covers purpose, filters, and deprecation status. The only gap is the absence of any note on return shape or volume, which is minor here.

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 100%, so all three filters (category, language, file_path) are already documented, including the auto-detection behavior. The description only restates that filters restrict output to relevant checks, adding no new semantics.

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 ('Retrieve SystemDox checks') with concrete examples of what a check is (banned patterns, required patterns, coding rules), and immediately distinguishes itself from the sibling `get_checks` by declaring itself the deprecated alias.

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 an explicit when-not ('DEPRECATED — use `get_checks` instead') plus the alternative by name, and removes ambiguity about whether it still functions by stating it works and giving a removal date of 2027-01-31.

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 burden and does so well for the most important trait: 'Read-only: this tool cannot create, move, or close board items' rules out writes explicitly. It also discloses the return shape (grouped by status, per-issue fields) and the true-totals behavior. It does not mention auth requirements or pagination beyond the 200-item limit, keeping it short of 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?

Front-loads the two modes immediately after identifying the resource, then closes with the safety constraint. Three sentences, each carrying distinct information; the field enumeration is long but directly useful for knowing what comes back.

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?

There is no output schema and no annotations, so the description must explain both return values and safety — it does both, including the per-issue fields and the true-total behavior of group headings. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns extra by tying project_number to a distinct output mode and confirming the status grouping (In Progress / Todo / Done) that the enum encodes. It adds mode-level meaning rather than merely restating parameter definitions.

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 (read) and resource (GitHub Projects boards in this workspace), and immediately distinguishes its two operating modes: bare listing of open boards with per-status item counts versus per-board issue listing. No sibling tool produces board data, so the agent can route here unambiguously.

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 context for both modes ('With no arguments...' / 'With project_number...') and states the intent behind each — survey the board, or drill into one board to 'pick up the right issue'. It lacks an explicit exclusion clause (e.g. when to prefer a sibling tool instead), but there is no real overlap with the listed siblings, so the implied guidance is sufficient.

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 full behavioral burden; it does establish that this is a read operation and lists the categories of data returned, which matters since there is no output schema. It omits permission/scope requirements, output format (IDs vs summaries), sizing or truncation behavior, and whether the aggregate call is expensive relative to the narrow getters.

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

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

Two sentences, zero filler, with the scope ('org-wide') and the contents front-loaded before the optional narrowing clause. Slightly dense enumeration rather than a fuller explanation of behavior, but 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?

For a zero-annotation, no-output-schema tool the description does the minimum viable job by naming what comes back and noting the optional repo focus. Missing is anything on response shape, how the target repo alters the payload (the schema mentions CLAUDE.md, which the description does not), and cost or filtering behavior.

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 100%, so the single parameter is already documented with format and intent, setting the baseline at 3. The description adds only that the repo focus is optional and that it narrows the context set, which mildly reinforces but does not extend 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 definition uses a specific verb ('Retrieve') with a named resource ('org-wide planning context') and enumerates the payload: connected repos with summaries, cross-repo dependencies, ADRs, and active specs. That makes the aggregate nature clear enough to separate it from single-artifact readers like get_docs or get_specs, though it never names those siblings explicitly.

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

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

There is no when-to-use guidance and no routing against the many adjacent get_* tools (get_context, get_specs, get_plan_board, get_project_rules). A reader can infer this is a planning-time aggregate read, but nothing states whether to call it first, when to prefer the narrower tools, or what 'active specs' means in terms of scope.

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 disclosure burden; "Retrieve" does signal a read-only operation, which is the key behavioral fact. Beyond that it says nothing about return shape, whether results are scoped to the current project, ordering, or permission requirements, so a read tool's modest risk profile is covered but not enriched.

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?

Three short sentences, front-loaded with the verb and resource, then the domain framing, then the filter. The category list partially repeats the schema enum, but it earns its place by conveying what kinds of rules exist rather than merely enumerating values.

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?

This is a simple read tool with one optional enum parameter and no output schema, so the description is close to sufficient. The notable gap is that with no output schema, the description never indicates what a returned rule looks like (fields, structure) or whether results are a list, leaving an agent to discover the shape at call 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 description coverage is 100% and the single parameter has a full enum, so the schema already documents the filter completely. The description adds only the intent that filtering narrows to "only relevant rules"; it does not explain matching behavior or what an unfiltered call returns, so the 3 baseline 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 gives a specific verb and resource ("Retrieve project rules") plus the source (SystemDox Standards), and it defines what a rule is — team-defined principles across deployment, architecture, security, testing, and process — which meaningfully separates it from siblings like get_guardrails, get_checks, and get_specs. It stops short of naming any sibling explicitly, so the differentiation is inferred from the domain framing rather than stated.

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

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

"Filter by category to get only relevant rules" implies the filter is optional and useful for narrowing, which is a light usage cue. However, there is no guidance on when to call this versus get_guardrails, get_checks, or get_specs, and no statement that omitting the filter returns everything.

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 full behavioral burden, yet it says nothing about whether the call is read-only, whether all templates are returned or paginated, whether results are scoped to a project, or what the response shape looks like. The examples explain template content but not tool behavior.

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

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

Two sentences, front-loaded with the action and resource, followed by illustrative examples. Nothing is wasted, though the second sentence spends space on examples rather than on behavior an agent needs.

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 simple zero-parameter read tool with no output schema, the description covers what the resource is but not what comes back or how it should be consumed. An agent can call it correctly but cannot predict the response, leaving a clear 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 no parameter semantics to add and the baseline of 4 applies. The description does not mislead about inputs, though it also does not clarify that the call is unfiltered and returns everything.

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 ('Retrieve reusable prompt templates') plus the source system ('SystemDox Standards'), and the examples clarify what a template is. It does not explicitly distinguish itself from the sibling create_prompt_template or the other get_* retrieval tools, so it falls short of a 5.

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

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

Usage is implied by 'preconfigured prompts that Gen AI should use when generating content,' which tells the agent the templates are meant as generation aids. There is no explicit when-to-call guidance, no exclusions, and no mention of how this differs from list_skills or get_specs, which an agent may confuse it with.

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 full burden, and 'Retrieve' does establish a read-only operation plus the internal structure of a spec. It does not disclose whether keyword search returns full specs or lightweight summaries, whether results are paginated or capped, or how the three parameters combine when supplied together.

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

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

Two sentences with no filler: the resource and its contents come first, then the three access modes. The parenthetical is informative rather than redundant, and nothing needs trimming.

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-optional-parameter read tool with no annotations and no output schema, the description covers what a spec is and how to fetch one, but leaves the return shape (list vs. full document), result limits, and default no-parameter behavior unspecified. That is a meaningful gap given nothing else describes the response.

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

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

Schema description coverage is 100%, so all three parameters (search, status enum, draft_id) are already documented in the schema, and the description mostly restates them. The one piece of added meaning is that draft_id yields 'full content' while search is names-only, but the schema's own 'with full content' wording already conveys that.

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

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

The description uses a specific verb ('Retrieve') on a specific resource ('SystemDox specifications') and even characterizes the payload (proposal, RFC 2119 requirements, Given/When/Then scenarios), which separates it from siblings like get_docs or get_checks by content type. It stops short of naming an alternative tool for overlapping lookups, so it falls just under the top mark.

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?

Three invocation modes are enumerated (by ID, by status, by keyword), which implicitly tells the agent when each parameter applies. However there is no statement of when NOT to use this tool, no mention of what happens with no parameters at all, and no routing to or away from get_docs/get_planning_context.

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

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

Annotations already declare readOnlyHint=true, and 'Reads only' merely restates that. The genuine added value is behavioral: the tool compares workspace configuration against the local machine and surfaces gaps plus remediation, which the agent could not know from the annotations or the empty 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?

Two short sentences, front-loaded with the return content before the call instruction, and no filler. The trailing phrase 'with what to do about it' is slightly colloquial but still carries information about remediation 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?

With no parameters and no output schema, the description carries the burden of explaining return content, and it does so by listing the five categories covered and the gap-analysis behavior. It leaves open the response shape and the scope (workspace-wide vs per-project), which keeps it short of full completeness.

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 and the baseline applies. The description correctly implies the call is parameterless by framing it as an unconditional workspace-vs-machine check.

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 resource ('this workspace's team setup') and enumerates its contents (skills, plugin, hooks, MCP servers, memory), plus the contrast with what the local computer lacks. That is far more concrete than the title, though it never names a sibling such as get_tech_stack or get_checks to disambiguate.

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

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

'Call it to check whether this computer is set up' gives an explicit trigger condition, which is more than most definitions offer. There are no when-not conditions and no pointer to an alternative sibling, so the agent must infer when a different get_* tool is the better choice.

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; 'Retrieve' implies a side-effect-free read and 'configured' hints the data comes from project configuration rather than live scanning. It also names the returned content (versions and notes), which helps, but it omits where configuration is sourced from, project scoping, and what happens when no stack is configured.

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

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

A single front-loaded sentence with zero filler: verb, resource, enumerated contents, and returned attributes. Nothing redundant or misleading.

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 simple zero-parameter read tool this is nearly sufficient, and the parenthetical partially substitutes for the missing output schema by listing what comes back. However, it never states scope (which project/workspace the stack belongs to) or the empty-state behavior, leaving gaps the agent cannot resolve elsewhere.

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 parameter semantics to add; the baseline for a no-param tool applies. Nothing in the description needs to explain argument 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?

States a specific verb ('Retrieve') and resource ('configured technology stack') and enumerates what it covers: languages, frameworks, databases, infrastructure. It does not explicitly differentiate from siblings such as get_specs or get_project_rules, but the name-resource pairing is distinctive enough that confusion is unlikely.

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

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

There is no guidance on when to call this versus alternatives like get_specs, get_project_rules, or get_context, nor any stated precondition such as requiring an initialized project. The agent must infer usage from the name 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?

Beyond readOnlyHint=false, the description discloses the concrete guardrail: it refuses and names the offending files when local edits are detected, with overwrite as the explicit bypass. It also states 'Never runs anything,' which is important safety context the annotations alone cannot convey for an installer.

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?

Three short sentences: what it does and where, then the refusal condition, then the safety guarantee. Zero filler and the most decision-relevant fact (destination) is front-loaded.

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 write tool with no output schema, the description covers destination, refusal behavior, and side-effect safety, which is most of what an agent needs. Minor gaps remain: it doesn't say whether the destination directory is created if absent, or what the tool reports on success (e.g., the list of installed files).

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 100%, so the baseline is 3. The description still adds meaning by pinning down the default target path and by tying overwrite to the edited-since-install refusal, which clarifies the interaction between two parameters rather than merely restating them.

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 (Install), a specific resource (a skill published to SystemDox), and the destination (this computer, defaulting to ~/.claude/skills/<name>/). The phrase 'published to SystemDox' implicitly frames it as the counterpart to publish_skill and distinct from list_skills, so an agent can route correctly 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?

It states the default install location and the exact condition under which installation is refused (a file edited since install), plus the escape hatch (overwrite true). That is strong conditional guidance, though it doesn't explicitly name sibling alternatives or address when to prefer a repo-local target over the global default.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is enumerating return fields (name, description, latest version). It doesn't mention ordering, pagination, or whether results are scoped to the caller's team, which would matter if the list can be long.

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

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

Two short sentences with no filler: the first defines the resource and its returned fields, the second hands off to the install path. Everything is front-loaded and nothing repeats the title or annotations.

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 no output schema, the description usefully compensates by naming the returned fields and pointing at install_skill as the successor action. Only minor gaps remain (ordering/pagination, scope of the listing) for a simple read-only enumeration tool.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning the description could add or omit. Calling convention is fully carried by the empty object 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 gives a specific verb and resource ("List the Claude Code skills published to SystemDox") plus the filter that matters (installable ones), so an agent can distinguish it from publish_skill or the get_* siblings. It stops short of explicitly contrasting with publish_skill, but the intent 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 states the follow-up path explicitly ("Use install_skill to install one"), which routes the agent to the correct alternative for the obvious next action. It doesn't say when not to use this tool or whether results are filtered by ownership/permissions, so it's clear context rather than 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?

Goes well beyond the bare readOnlyHint=false annotation: it discloses that each publish creates a new version of the team plugin that members accept at their next update, that instructions alone does not version, that an admin role is required, and that the server validates links, binaries and oversized files before sending anything. Those are exactly the side effects and preconditions an agent needs before committing to a write.

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 dense paragraph, front-loaded with the verb and the part enumeration, then prerequisites, then parameter guidance — each sentence carries information. It is long for a single block and could be split into bullets for scannability, but there is no filler.

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

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

For a three-parameter mutation tool with no output schema, the description covers purpose, part enumeration, permissions, versioning side effects, validation behavior and directory/file selection. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what `directory` should point at for each part and frames `files` as a fallback only ('Only when there is no folder to read') rather than an equal option. That prevents the most likely misuse of the schema, though it does not elaborate on file size limits or path normalization beyond what the schema already states.

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 ('Publish one part of your team's Claude Code setup to SystemDox') and enumerates exactly which parts exist and what files each maps to (hooks/hooks.json, .mcp.json, agents/*.md, commands/*.md, CLAUDE.md). This distinguishes it clearly from the sibling publish_skill and from all the get_* readers.

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 a clear rule for choosing between the two input paths — pass `directory` when the folder is on this computer and never retype files into `files` — plus the admin-role prerequisite for four of the five parts. It does not reference the sibling publish_skill or explain when to publish a part versus create artifacts another way, so it stops short of full alternative 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?

Annotations supply only readOnlyHint=false, so the description carries most of the weight and does add real behavior: the server performs the file read itself, and republishing the same name produces a new version rather than failing. That versioning semantics is the key non-obvious trait for a write tool. Still missing: what happens to the prior version's files, whether auth or space permissions are required, and what the call returns.

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?

Four short sentences, front-loaded with what the tool does and immediately followed by the operational instruction. Every sentence carries a distinct, actionable fact (what gets published, how to pass the folder, versioning, and the anti-pattern to avoid). No filler or restatement of the name/title.

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

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

For a mutation tool with six optional parameters, no output schema and a bare annotation set, the description covers the main risk areas: input mode selection, server-side reading, and version bumping. The remaining gap is the post-call picture — no mention of what is returned (version number, ID, URL) or what the agent should do next to install the published skill.

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 100%, so the schema already documents all six parameters, making 3 the baseline. The description adds modest beyond-schema meaning by framing `directory` as the preferred input that the server reads byte for byte and warning against mirroring it into `files`. It adds nothing about `name` defaulting, `note`, `spaceId`, or `baseVersion` beyond what the schema says.

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 ('Publish a Claude Code skill folder (SKILL.md plus its references and scripts) to SystemDox') and names the downstream outcome ('installed on any computer'). An agent can tell this is an upload/publication operation rather than a read. It does not explicitly contrast with the sibling 'install_skill' or 'publish_setup_part', which is the only reason it falls short of a 5.

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

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

It gives an explicit positive path ('Pass `directory`... the server reads the files itself, byte for byte') and an explicit negative rule ('Never retype the files into `files` when the folder is on this computer'), which resolves the directory-vs-files ambiguity an agent would otherwise hit. It also states that republishing a name creates a new version. It gives no guidance on when to prefer this over the sibling install_skill or publish_setup_part.

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?

The annotations only say readOnlyHint=false, so the key behavioral fact here — that the result is a draft requiring human review rather than a published record — is genuinely additive and important. However, the description says nothing about permissions, whether repeated calls create duplicates, or what the caller receives back (an ADR id? a link?).

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

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

Two short sentences, zero filler, and the action is front-loaded ahead of the consequence (draft ADR pending review). Nothing could be removed without losing information.

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

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

For a 5-parameter mutation with a fully documented schema and a safety annotation, the description covers what the tool does and the review-gated outcome. The remaining gap is the return value and duplicate-handling, which is a modest omission rather than a blocking one.

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 100% and each of the five fields carries its own example-rich description, so the schema already does the semantic work. The tool description adds no extra meaning about what belongs in context vs. decision, so baseline 3 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?

"Record an architecture decision" gives a specific verb and resource, and the second sentence clarifies that it produces a draft ADR in SystemDox. That is clearly distinct from every sibling (the get_* family and the create_check / create_guardrail / create_project_rule writers), though the description never names an alternative to reinforce the contrast.

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?

"Made during development" and "for human review" imply the moment to call it, but there is no explicit when-not guidance, no prerequisites (does the project need to be linked first?), and no mention of an alternative path such as just discussing the decision in chat.

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?

Annotations already declare readOnlyHint=true, and the description reinforces it ('Writes nothing') while adding genuinely new behavior: the resolved details are session-only and must never be persisted into a memory file, and resolution pulls from whichever vault holds the record. It omits failure behavior (invalid or unknown identifier) and does not describe pagination or rate limits, but the added data-handling constraint is significant context beyond the annotation.

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 identifier forms are front-loaded in the first sentence, and the constraint about not persisting details follows. It is dense with subordinate clauses and the colon-list construction is slightly heavy, 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?

With one parameter and no output schema, the description supplies what an agent needs: accepted identifier forms, the returned fields, the source vault, and the prohibition on writing the result into memory. The only minor gap is behavior on a non-resolving identifier, which is peripheral for a read-only lookup.

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 100% and the pattern plus example already document the single id parameter, so the schema does the heavy lifting. The description nonetheless adds real meaning by decoding the prefixes (con_ = label, ctc_, usr_) into the kinds of records they denote, which is not expressed by the regex.

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

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

Specific verb ('read back') plus resource ('a person') plus the exact identifier forms accepted (con_, ctc_, usr_) and the fields returned (label, name, phone, email). No sibling tool in the list touches persons, and the description makes that scope unambiguous 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 states the triggering context clearly: use this when a team memory references a person by identifier, and it implies the resolution step happens after reading a memory. It does not name an alternative tool or state what to do when an identifier is unknown, 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?

With readOnlyHint=false already declared, the description adds substantial behavior beyond the annotation: conflict resolution keeps both texts, files containing phone numbers, emails, or home-folder paths are skipped and listed rather than transmitted, and a member-run terminal command is surfaced. It never states what a completed run returns or how pulls/pushes are reported, which keeps it short of a 5.

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

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

The verb and scope lead, followed by the conflict rule, the privacy skip rule with its remediation command, and the dryRun hint. Every sentence carries distinct information with no restatement of the name or schema.

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

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

For a mutation tool with only a readOnlyHint and no output schema, the description covers the write profile, conflict handling, privacy filtering, remediation path, and safe preview mode. Nothing an agent needs in order to decide to call it or to interpret a skipped file 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 100%, so the baseline is 3, but the description adds meaning: dryRun is clarified as 'without writing or sending anything' (the schema only says 'change nothing', omitting the network aspect), and 'one project's team memory' frames the project parameter's scope.

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 ('Sync one project's team memory on this computer with SystemDox') and immediately enumerates the three concrete operations: pull team-changed files, push locally-changed files, keep both texts on conflict. That scope clearly separates it from every sibling, which are all read-only get_* or single-artifact 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?

The description gives clear context for invocation: it is a two-way sync of team memory files, and dryRun is offered for preview. It does not name an alternative tool or state when not to use it, but no sibling overlaps with this operation, so the practical gap is small.

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?

Annotations only cover readOnlyHint, and the trailing 'Read-only' adds nothing beyond that. However, the description does disclose non-obvious behavior: traversal is bidirectional, the path is shortest, each step carries provenance ('how it is known'), and overall confidence is bounded by the weakest step. That is real value beyond the annotation, though it omits what happens when no path exists within max_hops.

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?

Three tight sentences, front-loaded with the core operation before the weaker-link caveat. The only wasted clause is the trailing 'Read-only', which merely restates the readOnlyHint annotation.

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 output schema, the description should explain the return shape; it hints that each step reports how it is known, but never says the result is an ordered list of steps, nor what is returned when no path exists within max_hops. Adequate for a small read-only query tool, but a documented no-result case 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 100%, so from, to, and max_hops are already documented in the schema, including the default of 6. The description adds no extra meaning about parameter interpretation, so the baseline 3 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 operation on a specific resource: find the shortest connection between two documents by walking links in either direction. An agent can distinguish this from a plain link-listing tool like get_document_links, though no sibling is named explicitly.

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

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

Usage is only implied by the semantics of 'shortest way two documents connect'. There is no explicit statement of when to prefer this over get_document_links or get_graph_stats, nor any prerequisite (e.g., that both document ids must already 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?

Annotations only declare readOnlyHint=false, so the description usefully adds the draft-only precondition. However, it does not state that existing section content is overwritten, whether changes are reversible, or what permissions are required for a write 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?

Two sentences, front-loaded with the action and immediately followed by the critical draft-only constraint. No redundant or filler wording.

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

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

For a four-parameter mutation tool with no output schema and full schema coverage, the definition covers the key eligibility constraint. It could say more about the overwrite semantics and expected response, but nothing essential to invoking it 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 100%, so the baseline is 3; the description adds some value by listing the section values (proposal, tasks, requirements) in prose. It does not clarify the conditional requirement_name parameter, but the schema already documents that dependency.

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 ("Update an existing SystemDox spec") and names the editable sections (proposal, tasks, requirements). It does not explicitly differentiate from siblings like get_specs, but the mutating verb makes its role distinct.

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 a clear when-not condition: only draft specs can be modified, and published specs must be versioned first. It stops short of naming the exact tool or workflow for versioning a published spec.

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