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

Goes well beyond the annotations by disclosing preconditions (initialized project memory, candidate must be in ignored state), that it writes latent status with audit/snapshot references, that it does not reinstall removed native files, and that repeat activation fails once active — consistent with idempotentHint=false. The only weak spot is that the return-value sentence overlaps the output schema rather than adding new behavioral detail.

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 action and its preconditions, and nearly every clause carries distinct information (alternatives, preconditions, non-effects, failure mode). The sentence enumerating return values ('Returns the candidate, skill_file, and mutation references') is largely redundant given the output 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 single-parameter mutation with an output schema, the description supplies everything an agent needs: entry preconditions, alternatives, side effects on latent status, what it explicitly does not do, and repeat-call behavior. No meaningful gap remains.

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

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

Schema description coverage is 100% and the schema already explains that latent_skill_id is the exact candidate ID, not a canonical slug or file path. The description adds no parameter-level detail beyond that, 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 verb ('reactivate') and a precisely scoped resource ('an ignored latent skill candidate whose generated SKILL.md still exists and has valid frontmatter'). It explicitly distinguishes itself from create_skill, publish_skill, and sync_skills, so an agent can select it 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 names when to use it ('to reverse candidate deactivation'), which siblings to use instead for canonical creation (create_skill, publish_skill) and native copies (sync_skills), and the failure condition for repeated calls. Nothing about routing 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?

Annotations already flag destructiveHint=true and idempotentHint=false, and the description builds on that by naming what can be destroyed ('optional native replacement and synchronization can change native copies') and reassuring that 'Defaults avoid native replacement/sync'. It also warns 'inspect conflicts before repeating', which explains the non-idempotent hint. It stops short of saying whether adoption is reversible or how failures/rollback behave, so it is strong but not exhaustive.

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 sibling routing are front-loaded in the first two sentences, with behavioral caveats following. It is dense but the semicolon-chained clauses about defaults and return values make it slightly harder to scan than it needs to be; every sentence does still carry 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 7-parameter destructive mutation with full annotations and an output schema, the description covers routing, prerequisites, default safety posture, and a caution about conflicts. Return details are delegated to the output schema, which is acceptable, though a note on whether a prior adoption can be undone would close the remaining gap.

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

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

Schema coverage is 100%, so path, slug, scope, category, visibility, replace_native and sync_after_adopt are already fully documented. The description only reinforces defaults ('Defaults avoid native replacement/sync') and the initialization requirement tied to project scope, adding small marginal value rather than new syntax or format guidance. Baseline 3 is appropriate when the schema carries the 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 ('Register') plus resource ('existing canonical skill directory') and adds the constraint 'in UMEM while avoiding duplicate slugs'. It immediately distinguishes itself from the two closest siblings by name (import_skill, create_skill), so an agent can route 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?

Gives an explicit when-to-use rule ('unregistered canonical content') and names the alternatives with their selecting conditions: import_skill for an external/native source, create_skill for new content. It also adds a prerequisite ('Project scope requires initialization'), which is exactly the kind of gating an agent needs before calling.

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 declare non-read-only, non-idempotent, non-destructive, and the description explains exactly why: it persists a compiled context summary and audit event, and repeated calls create fresh records. It also discloses success/failure shape (status, context, skills or an error envelope) and negative scope, adding real value beyond the annotation flags.

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?

Six short sentences, front-loaded with the action and its substitutes, followed by prerequisite, side effects, exclusions, and return shape. Every sentence carries distinct information; none restates the name or annotations verbatim.

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 only cover call placement, prerequisites, and side effects, all of which are stated. For a zero-parameter aggregate tool with real persistence side effects, nothing material 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 is nothing for the description to disambiguate; the baseline applies. The description instead spends its words on behavior and call placement, which is the right trade-off.

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 three concrete resources (status, project context, skill catalog) plus the timing constraint (once at session startup). This clearly distinguishes it from the aggregatable siblings status, context, and list_skills, and from get_skill_detail.

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

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

Explicitly names the three calls it replaces, names the sibling to use instead for deeper catalog lookups, and states the prerequisite (initialized project memory). It also gives exclusions: it does not install skills or synchronize hosts, which routes the agent to the host/skill management 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it discloses that canonical content is preserved, that targets lacking suitable managed manifests are blocked, that no cleanup snapshot is created and sync_skills is the recovery path, and that the targets flag is inert. That is exactly the operational context an agent needs before invoking a destructive tool.

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

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

The description is front-loaded with purpose and alternatives, then caveats, then return/restore information — a sensible ordering and dense with signals. It is somewhat long and partially duplicates the schema's parameter text, but no sentence is empty.

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

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

For a destructive, three-parameter tool with an output schema, it covers purpose, alternatives, prerequisites, destruction scope, the no-snapshot caveat, recovery path, and named return fields (plan, removed_paths, warnings). Nothing an agent needs in order to call this 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 description coverage is 100%, so dry_run, targets, and skill_id_or_name are already documented in the schema with the same semantics the description restates. The description adds only the accepted identifier forms (ID, slug, unambiguous name) and the latent-candidate exclusion, which is marginal value over 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 (preview or remove) and resource (managed native copies for one active canonical skill), and explicitly scopes it as 'one active canonical skill' rather than project-wide. An agent can distinguish it from repair_skills and deactivate_skill 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?

It states when to use this tool ('cleaning that skill's installed runtime copies') and names both alternatives with the condition that selects them: repair_skills for orphan targets across the project, deactivate_skill for latent candidate state. Prerequisites (initialized project memory, resolvable skill identifier) are also given.

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

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

The annotations already declare readOnlyHint=false and idempotentHint=false; the description explains what those hints mean in practice by disclosing that it persists a generated summary and audit event, so repeated calls create new records even with identical arguments. It also adds a precondition (initialized project memory for project scope) and the failure condition for the size budget. That is real behavioral context beyond the structured fields, and none of it contradicts the annotation set.

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 tight sentences, front-loaded with the core action and immediately followed by the routing guidance. The final sentence enumerating return fields is largely redundant with the output schema, which is a minor waste, but everything else 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?

Given a write-side tool with persistence and audit side effects, the description covers the essentials an agent needs: prerequisites, scope exclusions, non-idempotency, and the size floor failure mode. With 100% schema coverage, an output schema, and annotations already present, nothing further is required.

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, and the description earns credit above that by explaining the operational consequence of scope (project requires initialized project memory; global excludes project content), which the schema does not state. The character budget is described as a compilation constraint rather than a mere parameter, reinforcing the max_size_chars semantics. It does not add anything about agent_session_key beyond the schema's own warning.

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 opens with a concrete verb and resource: 'Compile active facts, preferences, and rules into prompt-ready Markdown within a character budget.' It also distinguishes itself from the sibling it could be confused with, list_facts, by stating that list_facts is for inspecting individual records. An agent can select between them 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?

It states the intended use case ('Use for agent context'), names the alternative tool and its purpose ('use list_facts to inspect individual records'), and specifies scope preconditions ('Project scope requires initialized project memory; global scope excludes project content'). Both the when and the when-not are explicit.

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

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

Beyond the annotations, it discloses what is actually written (canonical content plus registration), the observable consequence of the sync flag (false avoids native copies, true synchronizes selected targets), the failure mode behind idempotentHint=false (repeated calls may conflict with an existing slug), and a hard precondition about project initialization. It also names the response contents, so an agent knows warnings and write references come back rather than a bare success.

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 comes first, then sibling routing, then preconditions, then write behavior, then return values — a sensible front-loaded order for an agent scanning for a routing decision. Each sentence carries distinct information; none is filler, and the density is justified by a ten-parameter mutation 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 non-idempotent write tool with ten parameters, this is complete: the agent learns when to pick it, when not to, what prerequisite must hold, what the sync flag changes on disk, what happens on repeat invocation, and roughly what comes back. Output-schema and annotation coverage are already supplied, and the description does not waste space duplicating them.

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 ten parameters in detail, including the sync default and the targets fallback. The description restates the sync behavior but adds little syntax or semantics beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter burden.

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 canonical Agent Skill") and names the inputs it is built from (name, purpose, triggers, optional Markdown). This is immediately distinguishable from siblings such as create_skill_draft, import_skill, and adopt_skill, which the description names 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 states the selecting condition ("explicit new skill request") and then routes to three alternatives by name — import_skill for external/native directories, adopt_skill for existing canonical content, create_skill_draft for an editable draft. It also adds a second exclusion for the edit case ("use update_canonical_skill to edit it") and a precondition ("Project scope requires initialization"), leaving nothing to infer.

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 destructiveHint=true and non-idempotent, and the description adds concrete behavior beyond them: an existing unregistered file at the draft path 'can be overwritten without confirmation' while only registered slug collisions are rejected, plus the advice to inspect the draft destination first. It also clarifies the non-obvious global-scope behavior that the physical file is not moved into user memory and that audit/snapshot writes use the project writer.

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 intent and alternative are front-loaded well, but the body is dense and partly redundant with the schema, restating the two draft paths and the global-scope registration nuance that the parameter descriptions already cover. Every sentence is informative, yet the same facts are repeated rather than compressed.

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

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

For a destructive write tool with an output schema present, the description covers the safety profile, scope semantics, overwrite risk, and the validate-before-publish workflow, so an agent has what it needs. It stops short of noting permissions/auth requirements, which is the only notable omission.

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 schema already defines all six parameters, but the description adds real meaning: the exact draft paths per scope (.umem/drafts/skills/<slug>/SKILL.md vs drafts/skills/<slug>/SKILL.md) and the defaulting rule that omitted/empty triggers fall back to the skill name and that supplied raw_markdown takes precedence. It goes somewhat beyond a baseline 3 by clarifying cross-parameter interaction.

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+resource ('Create an editable skill draft') and explicitly bounds the scope ('without canonical publication or native runtime writes'), then names the sibling it is contrasted with: create_skill for direct canonical creation. An agent can distinguish this from create_skill/publish_skill 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?

It states when to use it ('when content needs review'), names the alternative for the other case ('use create_skill for direct canonical creation'), gives a prerequisite ('Project scope requires initialization'), and adds a follow-up path ('Validate with validate_skill before publish_skill'). Exclusions and routing are explicit.

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

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

The annotations declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false; the description goes well beyond by disclosing what is and isn't destroyed (canonical SKILL.md preserved; native directories may be removed, stubbed, or preserved per host policy). It also warns that removed directories may lack recovery snapshots and confirms the non-idempotent behavior ('repeating the call fails once ignored'), and names the recovery path via activate_skill.

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 action and its scope are front-loaded in the first sentence, and each subsequent sentence carries distinct information (alternative routing, preconditions, destruction semantics, recovery). It is dense with multi-clause sentences, but no statement is 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 destructive one-parameter tool with an output schema and full annotation coverage, the description covers preconditions, policy-dependent side effects, irreversibility caveats, and the recovery tool. Nothing an agent needs before 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 schema already defines latent_skill_id and its disambiguation from slugs and paths, setting a baseline of 3. The description adds a state constraint not in the schema ('a latent ID in active state'), which meaningfully changes parameter validity.

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 ('mark an active latent skill candidate ignored and disable its recorded native installations') and immediately contrasts with the sibling cleanup_skill, which handles native cleanup of a canonical skill. The distinction between latent candidates and canonical skills is explicit, so an agent can choose between them 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 explicit when-to-use ('deactivate a latent workflow'), an explicit alternative with its condition ('use cleanup_skill for explicit native cleanup of a canonical skill'), and preconditions ('requires initialized project memory and a latent ID in active state'). It also notes the failure mode of repeating the call once ignored, which bounds usage.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description nonetheless adds real behavioral context beyond them: it does not repair or install anything, it tolerates an uninitialized environment, and it returns named checks with success/failure and recovery guidance. That is solid added value for a zero-parameter 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?

Three short sentences, front-loaded with the scope, then the alternative tool, then the behavioral caveats and return shape. Every sentence carries distinct information and none restates the tool name.

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 document return fields, and it appropriately summarizes them in one clause. Coverage of behavior and alternatives is adequate for a read-only diagnostic; the only missing piece is disambiguation from the several other health/layout-inspection 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 no parameters (0 properties, additionalProperties false), so there is no parameter semantics to explain; the baseline for a parameterless tool is 4. The description correctly implies no inputs are needed by framing it as a pure inspection call.

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 enumerates the concrete domains inspected (Python, storage, project layout, host integration health), so the agent knows exactly what it checks. It differentiates itself from host_setup explicitly, but says nothing about how it differs from closely-named siblings such as status, host_check, or inspect_project_layout, which limits it to a 4.

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

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

It gives explicit usage context ('Use for diagnostic checks') and names an alternative with the condition that selects it ('use host_setup to change configuration'). It also states a useful negative condition — it works on an uninitialized environment. It stops short of routing among the other health-adjacent siblings, so not 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?

Annotations only give the safety profile (destructiveHint=true, idempotentHint=false); the description goes well beyond them by disclosing exactly what gets written — skill content, native copies for enabled runtimes, and related state — plus drift protections under update_existing and the fact that warnings are returned for review.

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 most decision-relevant information (purpose, sibling routing, prerequisites) is front-loaded, and the sentences are dense with signal. It is borderline packed — six clauses in one paragraph — but almost nothing is 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, yet the description still names the return shape (generation details, paths, warnings, write references), and it covers prerequisites, side effects, and the update path for a destructive writer. Nothing material for a correct call 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 both parameters are already documented; the description nevertheless adds real meaning by tying latent_skill_id to 'eligible latent ID' prerequisites and clarifying that update_existing updates existing generated content while retaining native drift protections. It stops short of adding anything not already implied by the schema fields.

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 — 'Generate physical Agent Skill content for an approved latent candidate' — and immediately distinguishes itself from create_skill (new canonical content) and publish_skill (draft). An agent can select it without opening any sibling 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 when-to-use ('Use after proposal approval'), explicit alternatives with the conditions that select them (create_skill, publish_skill), and explicit prerequisites ('Requires initialized project memory and an eligible latent ID'). It also adds a pre-call caution: 'Review existing content before enabling updates or retrying.'

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 readOnly, idempotent, non-destructive and closed-world, so the description correctly spends its words elsewhere: a prerequisite ('Requires initialized project memory'), an explicit no-side-effect list, and failure semantics ('error when the selector is unresolved or ambiguous'). The only gap is that it doesn't discuss cost/latency or whether installation state is read live from the host, but for a read tool this is close to complete.

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

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

Four short sentences, front-loaded with what it returns, then when to use it, then prerequisites and exclusions, then error behavior. No sentence restates the name or the 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?

For a single-parameter read tool with an output schema, everything an agent needs to call it correctly is present: prerequisite project state, the sibling that supplies valid selectors, what it does not do, and how failure surfaces.

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 single parameter is already documented, so the baseline is 3. The description goes slightly further by framing the argument as a 'selector' that may be unresolved or ambiguous, which tells the agent that non-exact names are accepted but can fail and should be resolved via list_skills first.

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 plus a concrete resource set: 'Read metadata, triggers, content references, and installation state for one registered skill.' The scope ('one registered skill') distinguishes it from list_skills and from mutating siblings like activate_skill or sync_skills.

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 sequencing guidance ('Use after list_skills to inspect a relevant entry') plus named alternatives with their distinct roles: validate_skill for validation, recommend_skills for discovery. It also states negative scope ('Does not activate, generate, or synchronize skills'), closing off the most likely misselection.

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 description adds real behavioral context beyond the annotations: it does not rewrite the host manifest, but it does write an audit event, so repeated calls produce new records. That explains the readOnlyHint=false and idempotentHint=false flags, though it does not describe failure modes or what a failed validation returns. The return shape is listed, which is slightly redundant with the output 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?

Four tight sentences that front-load purpose, then usage, prerequisite, side effects, and return summary. Efficient overall, though the return-value sentence partially duplicates the output schema and could be trimmed.

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

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

For a validate-plus-audit tool with a simple 3-parameter schema and an existing output schema, the description covers purpose, prerequisites, side effects, and sibling routing. 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 100%, so host_id, max_chars, and max_lines are already documented with defaults and usage notes. The description adds nothing about parameters, which is acceptable given the schema does the heavy lifting, but it means no value beyond structured data.

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 pair: 'Validate an existing agent host instruction manifest and record the validation result.' It is clearly distinguishable from the nearby siblings host_setup (which creates) and doctor (broader diagnostics), both of which are named.

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

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

Gives explicit when-to-use ('after host_setup or to diagnose host readability'), an explicit alternative ('use doctor for broader diagnostics'), and a prerequisite ('Requires initialized project memory'). Little 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?

Annotations declare destructiveHint=true and the description does real work to qualify that: application goes 'through the snapshot/audit pipeline' and 'does not mean unrestricted overwrite of unmanaged files.' That is valuable context an agent would otherwise have to guess from a destructive hint. The only soft spot is that it doesn't spell out recoverability (e.g., rollback via snapshots) or that repeated application is not idempotent, both of which matter given idempotentHint=false.

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 dense and front-loaded: purpose first, then routing, then mode semantics. The closing sentence enumerating return values ('planned changes, validation, manual steps, warnings, and write references') is largely redundant with the existing output schema and could be dropped.

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 tool with full schema coverage and an output schema, the description covers the remaining unknowns: when to reach for it, what the mode flag changes, and how its write path is governed. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so host_id, force, max_chars, and max_lines are all already documented in the schema itself. The description restates the force semantics but adds no new meaning on format, host registry values, or how the two limit parameters interact beyond what the property descriptions say. Baseline 3 applies when the schema carries the load.

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 pair and resource: 'Plan or apply managed instruction configuration for a supported agent host.' It immediately scopes the tool by naming two siblings it is not ('use host_check to validate... and sync_instructions to refresh'), so an agent can pick correctly 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?

It gives an explicit precondition ('use after project initialization'), two named alternatives with their distinct purposes, and a decision rule for the main parameter ('force=false returns a plan; force=true applies'). That is when-to-use, when-to-use-something-else, and how to choose mode in one place.

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 flag destructiveHint=true and idempotentHint=false, and the description goes beyond them by localizing the danger: destruction only happens when replace_native/sync_after_import are enabled, defaults preserve the native source and skip sync, and repeated imports can collide with an existing canonical destination. That explains both the destructive and non-idempotent hints rather than merely restating them.

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 sibling routing are front-loaded in the first two sentences, then behavior and defaults. Dense but mostly earning its place; the return-value sentence ("Returns imported skill metadata, paths, warnings, and write references") is partly redundant given an output schema exists.

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

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

For a 6-parameter mutation tool with rich annotations and an output schema, the description covers routing, prerequisites, destructive opt-ins, defaults, and conflict risk. The only soft spot is the vague "requires initialization" reference, which does not name initialize_project explicitly.

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 schema already documents path, scope, category, visibility, replace_native, and sync_after_import with defaults. The description reinforces the safe defaults and adds the conflict caveat for repeat imports, but contributes no new per-parameter semantics beyond what the schema says; 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?

"Import an existing native or local skill directory into canonical UMEM storage" gives a specific verb (import), a specific resource (skill directory), and the destination (canonical storage). The following sentence explicitly separates it from adopt_skill (register existing canonical dir) and create_skill (new content), so an agent can discriminate it among 38 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?

Names both alternatives and the condition that selects each: external skill content → import_skill, existing canonical directory → adopt_skill, new content → create_skill. It also states a prerequisite ("Project scope requires initialization") that gates the default scope, which is exactly the kind of when-to-use context an agent needs before calling.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true. The description goes further where it matters: it discloses the possible npx skill install requiring Node.js and network access, states that managed content is reconciled rather than blindly replaced, and describes the return payload (connection results, warnings, manual fallback steps). That is additive, but describing return contents adds little when an output schema exists and the npx/network caveat is the only genuine behavioral disclosure beyond annotations, so a 3 reflects real but modest added value.

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 purpose, then alternatives, then caveats; every sentence carries information. It is dense and slightly long, and 'inspect them before retrying' is prescriptive filler relative to the rest, but nothing 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?

Covers the environment prerequisites (Node.js, network), what gets created or reconfigured, the reconciliation behavior, and the shape of the result including warnings and manual fallback. With an output schema present, nothing an agent needs before calling 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% and the single 'layout' parameter is fully documented in the schema, including the legacy-vs-shared semantics. The description never mentions 'layout' or its default, so it adds no meaning beyond the structured field — 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 verb and resource ('Initialize local project memory and configure detected agent connections') and immediately names the siblings it is not: inspect_project_layout and migrate_project_layout. An agent can pick this over its neighbors 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 an explicit selection rule — 'Use for a new workspace' — plus named alternatives with their triggering conditions ('inspect storage', 'share existing legacy content'). It also notes that repeat calls re-run connection validation, which is exactly the kind of when-not signal an agent needs before calling twice.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the description is not carrying the safety burden. It still adds real value by clarifying that no project initialization is a prerequisite and that migration warnings are surfaced—context the annotations cannot 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?

Three short sentences, front-loaded with purpose, then usage, then negative scope. The closing sentence about the return payload is largely redundant with the existing output schema, which is the only wasted 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 parameterless, closed-world read tool with a full output schema and rich annotations, the description covers purpose, timing, exclusions, and prerequisites. 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter-level claims are made or 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?

The first sentence gives a specific verb ("Inspect") and resource ("local project storage layout and roots"), including the migration-warning scope. It is easily distinguished from siblings like initialize_project and migrate_project_layout, which are named directly.

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 before initialize_project or migrate_project_layout when layout is uncertain" names the alternatives and the exact condition that selects them. It also states the inverse exclusions (does not initialize, copy, or remove content) and the precondition (no initialized project required), leaving nothing 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the bar is lower. The description still adds useful behavior beyond them: the project-scope initialization prerequisite and the fact that history is append-only and unaffected by this call. The statement about the returned events array overlaps the output schema, so no extra credit there.

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 the sibling routing are front-loaded in the first two sentences, and every sentence contributes something. The closing sentence about the events array is the weakest, since it restates what the output schema already provides.

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, full parameter coverage, and complete annotations, the description only needs to carry scope, prerequisite, and routing information, all of which are present. The one thing an agent might still wonder about is ordering, pagination, or volume limits on the returned events, which is not addressed.

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?

There is a single parameter with full schema description coverage and an enum, so the schema already carries its meaning. "For one memory scope" reinforces that the call targets a single scope rather than aggregating, but adds no syntax or edge-case detail beyond what the schema states. 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 opens with a specific verb and resource ("Read audit events") plus a scope qualifier ("one memory scope") and a purpose ("investigate prior operations and recovery references"). It explicitly differentiates from the nearest sibling by naming list_snapshots as the tool for recoverable snapshots.

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 when-to-use context (investigating prior operations and recovery references) and names an alternative tool with the condition that selects it (recoverable snapshots). It also surfaces a prerequisite ("Project scope requires initialization"). It stops short of a full when-not list, but for a narrow read tool that is a minor gap.

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, idempotentHint, and destructiveHint=false, so 'Does not change fact records' mostly restates them. The genuinely additive disclosure is the initialization prerequisite for project/combined scope, which annotations cannot express. Default/omitted-filter behavior is also spelled out, though it duplicates 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 purpose and the routing to 'context' are front-loaded, and most sentences carry information. Some space is spent repeating structured data ('Does not change fact records', 'Returns a facts array', default filters) that a reader already gets from annotations and schema.

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

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

With an output schema present, the description needn't explain return shape, and it covers the prerequisite, the sibling alternative, and default filter behavior. The only thing not addressed is retrieval sizing or result-bound behavior for what is effectively a list operation, a minor gap for a zero-required-parameter read 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?

Schema description coverage is 100% and two parameters are enums, so the schema already defines scope, status, and visibility values and defaults. The description's notes on omitted scope (searches both) and omitted status (active only) restate schema defaults rather than adding new syntax or edge-case meaning. 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 opens with a specific verb and resource ('Inspect individual memory facts') plus the dimensions being filtered (scope, lifecycle status, visibility), and it explicitly contrasts itself with the 'context' sibling for compiled prompt context. An agent can tell it apart from context, remember_fact, and purge_fact 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?

It states the selecting condition for this tool ('record IDs and metadata') and names the alternative with its own condition ('use context for compiled prompt context'), which is exactly the when-vs-alternative routing an agent needs. It also names a prerequisite: project or combined scope requires initialized project memory.

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, idempotentHint, destructiveHint=false and openWorldHint=false, yet the description contributes beyond them: a prerequisite ('Requires initialized project memory'), an explicit negative scope (no registration/sync/activation), and a state caveat ('unregistered directories remain unregistered'). These are exactly the side-effect boundaries an agent needs before calling in a skills-management suite.

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?

Content is front-loaded (verb+resource first, then routing, then constraints) and every sentence carries weight except the return-value sentence, which partly restates what the output schema already provides. Slightly dense but 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 an output schema present and rich annotations, the description only needs to supply routing, prerequisites, and boundaries — and it supplies all three. An agent has everything required to call this correctly at session start.

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 to add or omit. The description correctly avoids inventing inputs and instead spends its words on scope and prerequisites.

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 ('Read the catalog of canonical skills, native installation state, and latent candidates'), and explicitly differentiates itself from get_skill_detail (one entry) and recommend_skills (evidence-based candidates). An agent can identify exactly what this tool returns without inspecting 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?

It gives explicit when-to-use ('at startup through bootstrap or to find skill IDs'), names the two sibling alternatives and the condition that selects them, and adds a when-not clause ('Does not register, synchronize, or activate skills'). Nothing about tool selection 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?

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the bar is lower; the description still adds real context by ruling out mutation and disclosing that already-consumed snapshots are filtered out of results. It stops short of describing failure behavior on an uninitialized project or ordering/pagination of the array.

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 negative scope up front, and every clause carries information. The middle sentences are semicolon-packed, mixing alternatives with prerequisites in one line, which slightly hurts scanability.

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

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

Single optional parameter, safe annotations, and an output schema that carries the return shape; the description covers purpose, exclusions filtering, prerequisite, and sibling routing, leaving nothing an agent needs before calling 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 coverage is 100% with the enum documented, so the baseline is 3; the description earns an extra point by tying the project scope value to a precondition (initialization required) rather than merely restating the enum.

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 created recovery snapshots in one scope') and explicitly negates the misleading sibling interpretations ('Does not create or restore snapshots'), which distinguishes it from rollback_scope and from creation flows.

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 when-to-use ('Use before rollback_scope to inspect available recovery points'), names an alternative for a related need (list_audit_events for operation history), and states a prerequisite ('Project scope requires initialization').

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 destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it specifies exactly what is destroyed (migrated/already-shared facts are removed from the legacy facts file), what survives (private, global, conflicting facts stay local), that writes go through a snapshot/audit pipeline, and that shared content becomes visible to collaborators. That is precisely the behavioral context an agent needs before invoking a destructive migration.

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 purpose and alternatives, then moves to prerequisites, dry-run semantics, and side effects in a logical order. It is dense but slightly redundant, re-explaining dry_run=false behavior that the schema description already covers in near-identical 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 destructive, zero-required-parameter migration tool with an output schema, the description covers prerequisites, preview vs. apply, what is rewritten, what is preserved, safety pipeline, and the collaborator-visibility consequence. Nothing material is left for the agent 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 100%, so the baseline is 3; the description earns extra by explaining the consequence of the exclusion parameters ('private, global, and conflicting facts remain local') and the dry-run write path in outcome terms rather than restating types. It does not individually explain shared_operational_skill_slugs in the prose, leaving that to 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?

States a specific verb pair and resource set: 'Preview or migrate selected legacy project facts, rules, and skills into shared repository storage.' It immediately distinguishes itself from initialize_project (creates new storage) and share_skill (shares one skill), so an agent can pick it out of a 38-tool sibling list 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?

Names two concrete alternatives and the condition that selects them, plus a prerequisite ('Requires legacy content and filesystem access') and a pre-flight instruction ('Review private exclusions and source changes before applying'). The only minor gap is the absence of an explicit 'do not use when' clause, but the sibling contrasts effectively cover it.

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 annotations, which only declare non-read-only, non-destructive, non-idempotent. It discloses what gets written (canonical content), the status change to active, the recorded promotion metadata, the rejection of repeated promotion, and the fact that targets alone do not trigger native sync.

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

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

Front-loads the core action and then sequences alternatives, prerequisites, and side effects efficiently. It is slightly dense and repeats the targets/native-sync point already in the schema, but no sentence 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 return values need little elaboration, and the description still enumerates them briefly. Prerequisites, mutation side effects, rejection behavior, and the follow-up sync step are all covered for a state-changing promotion 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?

Schema description coverage is 100%, so all three parameters are already documented, including the recommendation_id eligibility rule and the targets sync caveat. The description mostly restates that same guidance, adding no extra syntax or format detail beyond 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?

States a specific verb and resource: promote a proposed, not previously promoted latent recommendation into a canonical Agent Skill. It also scopes the input by saying it must be a latent recommendation, distinguishing it from create_skill, publish_skill, and generate_skill.

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 sequencing (use after recommend_skills), names the alternatives with the conditions that select them (propose_skill + generate_skill for approval/generation, publish_skill for drafts), and adds a prerequisite (initialized memory for project-scoped promotion) plus a required follow-up (sync_skills for native install).

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 declare a non-read-only, non-idempotent, non-destructive mutation, and the description supplies the context they cannot: candidate state is mutated through a 'safe pipeline', a genuine project-memory prerequisite exists, and 'inspect state before repeating a decision' warns against blind retries given idempotentHint=false. The only soft spot is the undefined phrase 'safe pipeline', which is a minor gap against otherwise rich disclosure.

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

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

Front-loaded with purpose, then usage, then prerequisites, then decision semantics – a sensible ordering for an agent scanning for go/no-go signals. It is dense with semicolon-chained clauses and repeats the decision vocabulary already in the schema, which costs some tightness.

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

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

For a two-parameter mutation gated on project initialization, the description covers workflow position, prerequisites, all decision values, the no-decision review path, and a retry caution, while the output schema and annotations already carry return shape and safety profile. An agent has everything needed to call this correctly on the first attempt.

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 parameters are already documented, so the description's restatement of yes/y accepts, no/n ignores, and always records future approval policy largely duplicates the schema text. The one genuinely additive note is that an omitted decision returns a proposal plus follow-up choices, which extends beyond 'omit to review 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 and resource: review a tracked latent workflow candidate or record a decision about it. It immediately distinguishes itself from create_skill and ties itself to the track_latent_skill/recommend_skills pipeline, so the agent knows exactly which stage of the workflow this tool occupies.

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 upstream dependencies ('use after track_latent_skill or recommend_skills'), an explicit exclusion routing to a named sibling ('use create_skill for an explicitly requested new canonical skill'), and a hard prerequisite ('requires initialized project memory and a latent candidate ID'). Nothing about when to reach for this tool 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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real context on top: it writes canonical content plus registration, explains that sync=false leaves native targets untouched while true also synchronizes selected targets, and warns that publication can conflict with an existing slug, advising inspection before retry. It does not address reversibility of a published skill or permission requirements, which keeps it short of a 5 for a mutating tool.

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

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

Front-loads purpose in the first sentence, then usage, then behavior, with no filler. It is somewhat dense and clause-heavy (semicolon-chained behavior notes), but every sentence carries actionable information.

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

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

For a six-parameter mutating tool it covers purpose, sequencing, prerequisites, write scope, sync branching, and conflict handling, and an output schema already documents the return payload. 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 100%, so every parameter is already documented, including sync and targets. The description echoes the sync behavior visible in the schema and adds only the conflict-validation note for draft_or_path, saying nothing extra about slug, category, visibility, or targets; baseline 3 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?

States a specific verb pair and resource: 'Validate and publish an existing draft into canonical skill storage.' It also distinguishes itself from the editing sibling by naming update_canonical_skill, so an agent can separate the publish path from the modify path 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 places the tool in a workflow ('Use after create_skill_draft and validate_skill'), names the alternative for a different situation ('use update_canonical_skill to edit an already published skill'), and states a prerequisite ('Requires initialized project memory'). When-to-use, when-not-to-use, and sequencing are all 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: confirm=false rejects without applying, project/unscoped ID lookup requires initialization, and recovery must go through list_snapshots/list_audit_events rather than an assumed snapshot ID in the response. It also warns that repeating a purge may fail once the fact is gone, which directly explains the non-idempotent hint.

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 destructive scope constraint is front-loaded and every sentence carries information an agent needs. Some sentences are dense and run together (initialization requirement, snapshot/audit guidance, return fields), but there is no filler or repetition.

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

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

For a destructive three-parameter tool with an output schema, the description covers preconditions, sibling routing, failure modes, and recovery paths in addition to (briefly) the return fields. An agent could invoke this correctly and safely without consulting another tool's docs.

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, and the description genuinely adds semantics: it restates the id/scope mutual exclusion and the fail-if-both-omitted rule plus the mandatory confirm gate as operational constraints. It does not add format or sourcing detail beyond the schema, keeping it at a strong 4 rather than 5.

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

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

The opening sentence states a specific verb and resource ("Destructively remove one fact") and immediately names the two supported selection modes (by ID or by explicit scope). This distinguishes it cleanly from siblings like list_facts, context, and remember_fact without requiring the schema to be opened.

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

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

It explicitly routes the agent: use list_facts first to identify records, use context only for reading, and confirm=true is required or the call is rejected. It also states the exclusivity rule (id or scope, not both) and that omitting both fails, so the invocation preconditions are fully 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?

Annotations already declare readOnlyHint/idempotent/non-destructive, yet the description adds the critical clarification that the tool stays read-only 'even when dry_run=false' — the exact misreading an agent would otherwise make. It further discloses the evidence basis (recurrence plus nonempty curated evidence entries, duplicate summaries counted separately, not facts/logs/transcripts) and tells the agent to inspect returned thresholds and limitations first.

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 action and routing advice, and every sentence carries information. The read-only denial list ('promote, import, synchronize, create, or mutate') and the threshold sentence are dense and slightly repetitive with the schema, but the redundancy is defensible for a guardrail statement.

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?

Covers prerequisites, read-only guarantees, evidence sourcing, and hand-off to downstream tools; the return contents are summarized even though an output schema exists. For a three-parameter read tool in a large sibling set, nothing an agent needs before calling is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that dry_run=false does not enable writes and that evidence is counted from curated entries rather than fact/log scans. It does not restate the scope enum values beyond the prerequisite note, but nothing material is missing.

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 ('Review latent workflow recommendations') plus the exact evidence source ('explicit track_latent_skill evidence'). It also names the sibling it is not ('use list_skills for the full catalog'), 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?

Explicitly says when to use it ('choose candidates for proposal or promotion'), names the alternative for a different need (list_skills), and points to the downstream tools (propose_skill, promote_skill_recommendation) that consume the output. The prerequisite ('Project/all scope requires initialized project memory') is also 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description adds real context: writes flow through a 'safe mutation pipeline with audit/snapshot references' and repeated calls may append records rather than update in place – a non-obvious duplicate hazard the agent could not infer from the hints. It stops short of explaining failure modes such as what happens when secret detection rejects content, though the schema partly covers that.

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 front-loaded sentences: purpose, routing to alternatives, mutation behavior, and a safety exclusion. Every clause carries information and none repeats the schema verbatim.

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

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

An output schema exists, so return-value detail ('stored fact and write references') is only summarized, and annotations cover the safety profile. Combined with 100% parameter coverage and explicit sibling routing, 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?

Schema description coverage is 100%, so the schema already carries tag, scope and visibility semantics and the baseline would be 3. The description adds a workflow-level constraint tying the 'project' scope value to required project initialization, which meaningfully informs parameter choice.

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 ('Save a curated durable memory fact') and immediately scopes it with the optional tags/visibility modifiers. It explicitly names the two siblings it is not (track_latent_skill for repeated workflow evidence, list_facts for inspection), so the agent can discriminate 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 concrete when-to-use criteria ('learned preference or project decision'), routes the alternative case to track_latent_skill and inspection to list_facts, and states a prerequisite ('Project scope requires initialization') plus an explicit exclusion ('Do not store secrets or raw conversation logs'). Little 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?

The annotations already declare destructive=true and idempotent=false, but the description adds substantial behavioral context: it moves managed skill content, updates registration, rejects unmanaged destination conflicts, and explains that the old slug may stop resolving. These details go beyond the annotations and help an agent understand the side effects and retry risk.

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 organized: purpose first, then routing, prerequisites, mutation behavior, and retry caution. The sentence listing returned metadata, paths, warnings, and write references is somewhat redundant because an output schema exists, but overall the wording is efficient.

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

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

For a destructive rename operation, the description covers prerequisites, the alternative tool, managed-content movement, conflict rejection, and the risk that the old slug will no longer resolve. Return values are covered by the output schema, so the definition is complete enough for correct invocation.

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

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

Schema coverage is 100%, and the schema already documents both parameters, including that slug is the required new canonical directory slug and that skill_id_or_name must identify an active canonical skill. The description adds little parameter-specific meaning beyond what the schema provides, so the baseline 3 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 states a specific verb and resource: renaming an existing canonical skill slug and reconciling managed locations. It explicitly distinguishes this from update_canonical_skill, which handles content edits, so an agent can identify the tool's role 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 gives explicit when-to-use guidance for identity/path changes and names the alternative for content edits. It also states prerequisites (initialized project memory and an active canonical selector) and warns the old slug may not resolve after success, including an inspect-before-retry instruction.

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 annotations (destructiveHint=true, readOnlyHint=false) by disclosing what is NOT destroyed ('Does not delete canonical skills') and that no recovery snapshot exists, plus a safety instruction to inspect the plan first. It also explains the two-flag gating behavior and what the response contains, which the annotations cannot 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?

Front-loaded with purpose, then routing, then flag behavior, then safety caveat — a sensible order with no filler. It is dense and slightly run-on across clauses, and the flag explanations partially echo the schema, but every sentence carries operational meaning.

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

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

For a destructive two-flag tool this covers everything an agent needs: prerequisite, alternative tool, flag gating, non-destructive side guarantees, absent recovery path, and response contents. With an output schema present, it is not obligated to explain return values further.

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 the interaction semantics — that remove_orphan_targets=false selects no action even if dry_run=false — which clarifies the consequence of the default state rather than restating flag names. It stops short of adding new format or edge-case detail beyond 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?

States a specific verb pair and resource: 'Preview or remove orphan managed native skill targets across the project.' It also names the scope (project, orphan, native targets) and explicitly contrasts with the sibling cleanup_skill, so an agent can distinguish it 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?

Gives an explicit when-to-use ('Use for stale installations'), names the alternative tool and its narrower scope ('use cleanup_skill to inspect one registered skill'), and states a prerequisite ('Requires initialized project memory'). Both routing and preconditions 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real value by explaining what is destroyed ('current state covered by that snapshot') and why non-idempotency matters ('a second call can select a different snapshot, so inspect results before retrying'). The only redundancy is the return-value sentence, which an output schema already covers.

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

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

Dense and front-loaded: the restore effect comes first, then prerequisites, then the destructive-retry warning. The one expendable sentence is the return-value summary, which the output schema already supplies.

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

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

For a destructive, non-idempotent mutation this covers everything an agent needs: effect scope, pre-inspection siblings, the confirm gate, the initialization prerequisite for project scope, and the retry hazard. Return values are handled 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?

Schema coverage is 100%, so both parameters are already documented, but the description contributes a precondition not present in the schema: project scope requires initialization before rollback can succeed. The confirm semantics restate the schema's default-false rejection behavior rather than adding to it.

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 ('Restore the latest created snapshot in a scope') plus the exact effect ('replacing current state covered by that snapshot'), which cleanly separates it from the read-only siblings list_snapshots and list_audit_events it names.

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 directs the agent to run list_snapshots and list_audit_events before choosing recovery, states that project scope requires initialization, and explains that confirm=true is required while false rejects without restoring — covering both the when-to-use and the gate condition.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds materially: existing files at matching destination paths can be overwritten with no conflict check and no overwrite confirmation, there is no preview mode, operational content additionally needs confirm_operational=true, and writes go through a snapshot/audit pipeline. It also discloses the re-share behavior that updates registration and policy again, which is exactly the non-idempotent semantics an agent needs.

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

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

Front-loaded with purpose and the sibling contrast, then danger disclosure, then prerequisites, then return shape. Slightly redundant: registration updating is stated both in 'updates registration' and again in the closing sentence about re-sharing, though the latter adds the policy-reset nuance.

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?

Covers mutation risk, prerequisites, overwrite behavior, the missing preview mode, the operational confirmation gate, and the return payload ('shared skill, paths, warnings, and write references'), which is reinforced by an existing output schema. Nothing an agent needs before invoking this destructive tool 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 all three parameters, including the category enum and skill_id_or_name resolution guidance, are already documented in the schema. The description echoes the operational/confirm_operational requirement and the resolvability constraint but adds no syntax or resolution detail beyond the schema. Baseline 3 applies when the schema carries parameter 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 ('Copy an existing project skill into shared repository content for collaboration') and immediately contrasts it with the sibling sync_skills ('distribute native copies without changing visibility'). An agent can distinguish this from import_skill, adopt_skill, or publish_skill using the description alone.

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 when-to-use ('deliberate sharing'), an explicit alternative with its distinguishing condition (sync_skills), prerequisites ('Requires initialized project memory and a resolvable project skill'), and a pre-call action ('Inspect existing destination files and remove private information before calling'). This is close to the full when/when-not/alternatives rubric.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds real value by asserting the absence of side effects on memory records and host configuration, and by noting the returned payload includes recommended actions and initialized=false. It does not discuss cost, latency, or permission requirements, 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 purpose, then usage routing, then the negative guarantee and return shape. Every sentence carries distinct information with no restatement of the tool name 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?

For a zero-parameter read tool with a declared output schema, the description covers the only gaps that matter: what is inspected, when to prefer doctor or bootstrap, and that no state is mutated. 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the call is argument-free by framing it as an inspection of ambient project state.

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 ("Inspect") and resource with an explicit enumeration of what is surfaced: project initialization, fact counts, storage size, registered skills, and host validation status. An agent can distinguish this read-only status probe from mutations like initialize_project or host_setup 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 both positive triggers ("before initialization", "to diagnose whether context can be loaded") and explicit alternatives ("use doctor for environment diagnostics and bootstrap for session startup"). It also states exclusions ("Does not change memory records or configure hosts"), which routes the agent away from write-oriented 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?

Annotations only declare destructiveHint=true and non-idempotent; the description adds what is actually written ('managed instruction blocks'), that writes carry recovery/audit references, that apply=false is a no-write preview, and that the tool does not authorize overwriting unrelated host content. It also previews the return shape (planned changes, validation, warnings, manual steps), which is meaningful scoping beyond the annotation flags.

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 purpose, then usage, then behavior, and every clause carries information. The semicolon-chained middle section is dense and slightly run-on, which costs a point against a maximally clean 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?

Covers the prerequisite, the sibling routing, the preview-vs-write distinction, and the write safety boundary; an output schema exists so return values needn't be fully enumerated. Nothing an agent needs to call this 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 100%, so the baseline is 3; the description still adds consequence-level meaning for apply by contrasting 'previews' against 'writes managed instruction blocks with recovery/audit references.' It does not restate host_ids defaults, but those are already documented 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?

States a specific verb and resource: 'Plan or apply active-rule synchronization into selected agent instruction targets.' It immediately differentiates itself from the two nearest siblings by naming sync_skills (native skill directories) and host_setup (initial host configuration).

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 trigger ('Use after changing approved rules'), explicit alternatives with the condition that selects each ('use sync_skills for...', 'host_setup for...'), and an explicit prerequisite ('Requires initialized project memory'). Nothing about when to choose this tool 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?

Annotations already flag a destructive, non-idempotent write, but the description adds real context beyond them: native copies are written, drift_decision=keep preserves divergent content while overwrite replaces managed copies, and repeated sync still produces audit records. The warning to 'review drift before overwriting' is valuable, though it doesn't detail what is irreversibly lost on overwrite.

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

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

The purpose is front-loaded in the first sentence and each subsequent sentence covers usage, prerequisites, or behavior. Some restatement of the drift_decision semantics already in the schema is slightly redundant, but nothing is 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?

An output schema exists, so return values needn't be spelled out, yet the description still notes per-skill results, warnings, and optional gitignore checks. Combined with the prerequisite and drift-decision guidance, an agent has everything needed to invoke this write tool safely.

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 four parameters are already documented, and the description's drift_decision phrasing largely restates the schema text. It adds only a light operational cue ('review drift before overwriting') rather than new semantics for targets or skill_id_or_name, 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 verb and resource ('Synchronize one or all active canonical skills into native runtime directories'), including scope (one vs all). It explicitly separates itself from siblings sync_instructions and import_skill, so the agent can route correctly 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 an explicit trigger ('Use after canonical content changes'), names two alternatives with their distinct roles, and states a prerequisite ('Requires initialized project memory'). This is close to ideal 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?

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=false; the description goes beyond them by explaining matching semantics (proposed/active candidates gain recurrence, otherwise a new proposed candidate is created), the project-scope initialization prerequisite, and the negative behavior 'Does not publish or generate skill files'. But 'not idempotent' largely repeats idempotentHint=false, and the returned fields are already covered by the output 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?

Front-loaded with the core action, then constraints, prerequisites, side effects, and next steps in a logical order. It is dense but nearly every clause carries distinct information, though the closing list of prohibitions and returns is slightly compressed into a run-on.

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?

Return values are summarized and an output schema exists, safety-relevant behavior is covered by annotations plus narrative, the initialization prerequisite is noted, and the follow-up path is spelled out. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so the schema carries the per-field burden and the baseline is 3. The description adds prerequisite context for the scope parameter ('Project scope requires initialization') and reinforces that evidence must be sanitized, which ties to evidence_summary beyond what the schema 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?

The description states a precise verb pair and object: 'Record curated evidence of a repeated workflow and create or increment a matching latent skill candidate.' It explicitly draws boundaries against sibling tools ('use remember_fact for preferences and create_skill for an explicit new skill request'), so an agent can identify the tool 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?

Explicit when-to-use ('Use only for recurring workflow observations'), explicit when-not-to-use with named alternatives (remember_fact, create_skill), a next-step recommendation (recommend_skills or propose_skill), and a prohibition on submitting secrets, raw logs, or transcripts as evidence.

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 mark this as destructive, non-readonly, and non-idempotent. The description adds that writes go through a safe pipeline, that sync=true propagates to native targets subject to drift_decision, and that repeated calls can create audit/snapshot records even when content matches. Those side effects and drift behavior go beyond the annotations without contradicting them.

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 compact, moving from purpose to alternatives to prerequisites to behavior. The sentence about return values is somewhat redundant with the output schema, and the density of semicolon-separated behaviors is high, but there is little wasted 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 destructive canonical write with four parameters, many sibling alternatives, and an output schema, the description covers prerequisites, side effects, drift handling, and returns. It is complete enough for an agent to call correctly without needing the schema for safety context.

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 input schema already defines each parameter. The description adds relationship-level meaning: sync=true also updates native targets, those updates are subject to drift_decision, and an active canonical selector is required. That is useful beyond the individual field descriptions, though it does not restate raw_markdown 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?

The description begins with a specific verb and resource: 'Validate and replace Markdown content for an existing canonical skill.' It explicitly distinguishes this tool from update_skill and rename_skill, so an agent can identify its scope 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 'Use for canonical edits' and names the alternatives for latent metadata and slug changes. It also gives clear prerequisites: initialized project memory and an active canonical selector. This is explicit when-to-use guidance with sibling alternatives and a required 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 destructiveHint=true and idempotentHint=false; the description adds the concrete consequence (omitting raw_markdown can discard a customized body even with no other edit supplied), the write path (safe pipeline), side effects on native copies including divergence preservation, and that repeated calls create additional audit records. That is materially more than the annotation flags 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 routing decision, prerequisite, and destructive caveat are front-loaded in the first two sentences, which is the right ordering. A few clauses are redundant with the input schema (the omit-retains/regenerates rules appear in both places), costing a point, but no sentence is 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 destructive five-parameter mutation with a sibling that handles near-identical work, the description covers the prerequisite, the alternative tool, the main failure mode, side effects, and even the return shape, despite an output schema existing. 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?

Schema description coverage is 100%, so the baseline is 3; the description restates the omit-retains-stored-fields rule that the schema already documents for metadata. It earns one step above baseline by adding the operational workflow for raw_markdown (read existing, supply full edited content with compatible frontmatter) and by underscoring that the ID must not be a canonical slug or file path.

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 names a specific verb pair (update metadata, rewrite generated Markdown) and a precise resource (an existing latent skill). It immediately contrasts with the sibling update_canonical_skill, so an agent can route between latent and canonical edits without inspecting 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?

Explicit routing guidance is given ('Use for latent candidate edits; use update_canonical_skill for direct canonical content replacement') plus a prerequisite ('Requires initialized project memory and a latent candidate ID'). The dangerous case is also flagged with a remedy: omitting raw_markdown regenerates the file, so read the existing file and supply complete edited Markdown to retain custom content.

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 cover readOnly/idempotent/non-destructive safety, but the description adds non-obvious behavior: no project init needed, and the crucial caveat that a successful tool envelope does not mean the skill is valid — the report's errors and warnings must be inspected. That is exactly the kind of semantic warning annotations cannot carry.

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 sentences, all load-bearing, with the operation stated first and prerequisites, alternatives, and the report caveat following in priority order. Slightly dense but no filler sentences.

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 read-only validation tool with an output schema, the description covers everything an agent needs: supported inputs, prerequisites, sibling boundaries, and how to interpret the returned report versus the envelope status.

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 restates that an ID/name or path is accepted, which mildly reinforces but does not extend what the schema already documents, and the optional scope parameter is left entirely to 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?

"Validate a draft, registered canonical skill, or local skill file/directory" names a specific verb and enumerates the three input forms it accepts, immediately separating it from sibling tools like publish_skill and get_skill_detail. The added constraint "without publishing or changing skill content" pins down the scope of the operation.

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 timing ("before publish_skill or after editing a skill") and names an alternative ("get_skill_detail reads registered metadata") so the agent knows which sibling handles the adjacent task. It also notes that project initialization is not required at this interface, removing a common false prerequisite.

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