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

Annotations already establish readOnly, idempotent, non-destructive behavior. The description adds genuinely useful non-annotation context: there is no output schema, so describing the returned SKILL.md payload (guidance, examples, file references) tells the agent what it will get. It stops short of noting any side effects or preconditions for skill existence.

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 purpose and return content, then the imperative usage block. The emphasis block is somewhat repetitive ('NEVER just announce...' plus 'BLOCKING REQUIREMENT'), but this redundancy is functional for steering agent behavior rather than filler.

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

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

With no output schema, the description appropriately covers the return payload, the parameter source, and the invocation timing an agent needs. What remains thin is failure behavior (e.g., unknown skill name), 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?

Only one parameter exists and schema description coverage is 100% ('Skill name from <available_skills>'), so the schema already carries the semantics. The description adds no format or matching guidance beyond implying the skill must be relevant, 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 ('Load a skill's full instructions') and immediately clarifies the return value ('complete SKILL.md content with step-by-step guidance, examples, and file references'). This clearly distinguishes it from the skill-config-* and skill-display-* siblings, which manage configuration rather than executing/loading 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?

Gives decisive when-to-use guidance: invoke immediately when a skill is relevant to the user's task, and explicitly forbids merely announcing a skill without calling the tool. It does not name alternative tools or exclusion conditions, but the siblings are not substitutes for loading, so the missing piece is minor.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds only that the tool surfaces an interactive UI rather than returning data, which is mild extra context; it says nothing about what the UI does or how the call resolves.

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

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

Two short sentences, action first, trigger second, zero filler. Nothing could be removed without losing information.

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

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

An output schema exists, so return values need not be described, and with no parameters and full annotation coverage the definition is nearly complete. The only shortfall is the absence of disambiguation from the sibling skill-config-* mutation tools.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to explain or compensate for, and none is needed.

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

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

The description states a specific verb and resource: 'Open the skills directory configuration UI.' That is concrete and distinguishes this as the UI-opening tool. However, it does not explicitly differentiate itself from the many skill-config-* siblings that perform the underlying add/remove operations, and the second sentence blurs that line.

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

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

It gives a when-to-use trigger ('Use when user wants to configure, add, or remove skill directories'), which is more than nothing. But it names no alternatives or exclusions, and the overlap with siblings like skill-config-add-directory and skill-config-remove-directory risks misrouting the agent to this UI tool when a direct mutation tool is intended.

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 this is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds nothing beyond that - it does not say whether the entry persists across sessions, whether duplicates error or silently succeed (idempotentHint implies the latter), or when the allowlist takes effect. No contradiction with annotations, but minimal 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?

A single short sentence with no filler and the action/scope front-loaded. It is arguably under-specified rather than padded, which is penalized in other dimensions rather than this one.

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

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

An output schema exists, so return values need no explanation, and the single parameter is fully documented. However, for a config-mutating tool the description never explains the surrounding context: what the allowed list governs, required permissions, or how it relates to the origin/directory 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?

Only one parameter with 100% schema description coverage, so the schema already explains 'GitHub organization name to allow.' The description contributes no additional format constraints (case sensitivity, whether 'owner' vs full URL is expected). Baseline 3 applies when the schema does the work.

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: adding a GitHub organization to an allowlist scoped to skill repos. It is distinguishable from skill-config-remove-allowed-org, though it does not clarify the distinction from the similarly named skill-config-add-allowed-origin (org vs origin), which is the sibling most likely to be confused with it.

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

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

There is no guidance on when to add an org versus an origin, no prerequisites (e.g., admin/config scope), and no indication of what effect the entry has on skill loading. The agent must infer all of this from the tool name alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, repeatable local mutation. The description adds only that the mutation is scoped to well-known publishers; it does not describe auth requirements, whether the origin persists across restarts, or any failure behavior.

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

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

A single front-loaded sentence with an inline example and zero filler. Every element earns its place.

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

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

For a single-parameter configuration tool with a full schema, an output schema, and safety annotations, the description covers what is needed to invoke it correctly. It is only slightly thin on the operational context of what acquiring this allowance enables.

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 fully documented, including the normalization rule (only scheme + host[:port] is stored). The description adds the 'HTTPS' constraint, which the schema itself does not enforce, giving marginal extra value over the schema baseline.

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 (add) and resource (an HTTPS origin to the allowed list for well-known publishers), which is clearly distinct from the sibling skill-config-remove-allowed-origin. It does not explicitly name siblings, but the add/remove pairing makes the intent unambiguous.

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

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

The description says what it does but never states when to use it versus alternatives, prerequisites, or the effect of adding an origin. The inverse sibling implies the add/remove choice, but no explicit routing guidance or when-not-to-use condition is given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false and idempotentHint=false. The description adds nothing beyond that profile: it doesn't say whether adding a duplicate directory is rejected or duplicated, whether the change persists, or whether existing entries are affected.

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

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

A single front-loaded sentence with no waste. It is appropriately sized, though that economy comes at the cost of the missing guidance noted elsewhere.

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 mutating configuration tool with no explanatory power in the description, key facts are missing: whether the directory must already exist, whether the config is persisted, and how the change interacts with remove-directory. An output schema exists, so return values need not be described, but the preconditions are 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 description coverage is 100% and the single parameter ('directory', absolute path) is fully documented in the schema. The description adds no syntax, format, or constraint detail beyond it, so the baseline of 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 states a clear verb+resource ('Add a skills directory to the configuration'), so the agent knows exactly what operation is performed. It does not, however, differentiate itself from the obvious sibling skill-config-remove-directory or explain how it relates to skill-config-add-allowed-org/origin.

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

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

There is no when-to-use guidance, no prerequisite about the config needing to exist or the path needing to be valid, and no mention of alternatives. The agent must infer everything about context from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered. The description merely restates the removal action and adds nothing beyond the structured fields, e.g. what happens if the org is not in the list or whether the scope is global.

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

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

A single efficient sentence with no filler, front-loaded with the action and target. It is not under-specified so much as terse.

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 one-parameter config mutation with rich annotations and an output schema, the description is minimally adequate. The annotations carry the mutation semantics and the output schema carries the return shape, so little is missing, but the description does nothing to help route between it and its origin sibling.

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

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

Schema coverage is 100% and the single 'org' parameter is fully documented in the schema. The description adds no syntax, format, or sourcing detail beyond it, so the schema does all the work - the baseline 3 for high coverage.

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: 'Remove a GitHub organization from the allowed list.' An agent knows what it does. However, it does not differentiate from the sibling skill-config-remove-allowed-origin, which removes an origin rather than an org - a distinction the description leaves implicit.

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

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

No when-to-use guidance, no prerequisites, no mention of the sibling add/remove tools or which one applies. The removal context is only implied by the name and sibling set.

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds only the constraint that the target is an HTTPS origin in a specific list, without saying what happens if the origin is absent or whether removal is reversible.

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

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

A single front-loaded sentence with no wasted words. It is tight, though a touch more context could be added without bloat.

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 rich annotations and an output schema present, the description need not explain returns, but for a destructive config-mutation tool it omits any note about effect on the skill's behavior or error conditions. Adequate but with a clear gap.

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

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

Schema coverage is 100% and the single 'origin' parameter already documents exact-match semantics. The description's mention of an 'HTTPS origin' restates the resource but adds no syntax, format, or normalization 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 (Remove) and resource (HTTPS origin from the well-known allowed list), which distinguishes it from the sibling skill-config-add-allowed-origin. The phrase 'well-known allowed list' is slightly jargon-heavy but the direction of the operation is unambiguous.

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

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

No indication of when to use this versus skill-config-add-allowed-origin or the broader skill-config tools, and no prerequisites (e.g. auth, that the origin must already exist) are stated. Usage is only implied by the verb.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it never says whether the skills inside the directory are unloaded, what happens if the path is not registered, or whether a confirmation/failure response is returned.

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

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

One short sentence, front-loaded with the action, with no filler or redundancy. It is efficient, though its brevity reflects missing guidance rather than disciplined editing.

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

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

An output schema exists so return values need not be described, and annotations cover safety semantics. However, for a destructive config mutation with sibling tools, the definition omits any operational caveats (state of existing skills, error cases), leaving it merely minimal rather than complete.

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

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

Schema description coverage is 100% and there is a single required parameter with a clear schema description ('Absolute path to the skills directory to remove'). The description adds no format or validation detail, 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 ('Remove') and resource ('skills directory from the configuration'), which is enough to distinguish it from the inverse 'add-directory' sibling. It does not explicitly name or contrast with any sibling, but the lexical clarity is high.

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

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

There is no statement of when to use this tool versus 'skill-config-add-directory', no prerequisites (e.g., whether the directory must currently be registered), and no warnings about the effect on already-loaded skills. Usage is only implied by the verb.

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, idempotent, non-destructive toggle, and the description usefully adds what static mode means (skills list frozen at startup). It does not say when the freeze takes effect (immediate vs restart) or whether the setting persists, which matters for a config toggle.

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

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

One sentence, front-loaded with the action and followed by the clarifying definition of static mode. No filler.

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

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

An output schema exists so return values need no explanation, and the toggle's effect is described. However, for a config mutation an agent still lacks timing/persistence details and any reason to choose this over related skill-config tools.

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

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

The single 'enabled' boolean is fully documented in the schema (100% coverage), and the description's verb pair 'enable or disable' maps cleanly onto it. No additional semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (enable/disable) and resource (static mode), plus parenthetical explanation of what static mode does ('freezes skills list at startup'). Distinguishable from sibling config tools by its static-mode subject, though it does not explicitly contrast with any sibling.

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?

No guidance on when to enable vs disable static mode, no prerequisites, and no mention of alternatives among the many skill-config-* siblings. The agent must infer intent from the name alone.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, yet the description asserts the tool "configure[s] their invocation settings" and lets users "toggle assistant/user invocation" — an explicit mutation claim. That inconsistency directly misleads an agent about side effects, and the description adds no compensating disclosure (no persistence semantics, no delimitation from skill-display-update-invocation).

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

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

Two short sentences with the action front-loaded and no filler — efficiently sized for the call. The second sentence, however, spends its words on behavior that belongs to a sibling tool, so not every sentence fully earns its place.

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

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

An output schema exists, so return values need no explanation, and the empty parameter set is trivially covered. What is missing is a correct account of the tool's effect and its boundary against skill-display-update-invocation, both of which the current text muddies.

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 of 4 applies. No param-level meaning is needed or 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?

It gives a concrete verb+resource ("Open the skill display UI to view available skills"), which is clear enough on its own. However, it then claims the tool also exists to "configure their invocation settings," territory that sibling tools skill-display-update-invocation and skill-display-reset-override own, so the boundary with siblings is blurred rather than sharpened.

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?

A trigger is supplied ("Use when user wants to see skills or toggle assistant/user invocation"), which is more than most definitions offer. But no when-not condition or alternative is named, and half the stated trigger ("toggle invocation") points at a different tool, so the guidance can misroute the agent.

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=true, and destructiveHint=false. The description adds the key behavioral fact the annotations cannot convey: that custom overrides are discarded and reverted to frontmatter defaults, which tells the agent what is lost and what the post-state will be.

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

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

A single, front-loaded sentence with zero filler; the action and its resulting state are stated immediately.

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

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

With an output schema covering return values and annotations covering safety and idempotency, the description supplies the one thing they lack: the reversion target. It is complete for invocation, though routing guidance against the update sibling 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 description coverage is 100% and the 'setting' enum's '(omit for both)' semantics are documented in the schema itself. The description adds no parameter-level detail beyond what the schema already provides, 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?

Specific verb (reset) plus resource (a skill's invocation settings) and a clear target state (frontmatter defaults). It implicitly distinguishes itself from skill-display-update-invocation by describing reversion rather than mutation of custom values, but it never names that sibling, so differentiation is left to inference.

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

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

The description states what reset means but gives no when-to-use guidance, no prerequisites, and no explicit contrast with skill-display-update-invocation, which an agent must choose between. Usage context is only implied by the word 'reset'.

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, destructiveHint=false, openWorldHint=false, so the mutation/idempotency profile is covered structurally. The description adds nothing beyond that — it does not say what is changed, whether the update is reversible, or what permissions are required. No contradiction with annotations, but no added context either.

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

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

A single short sentence with no wasted words, reasonably front-loaded. However, brevity here reflects under-specification rather than disciplined concision.

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

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

An output schema exists so return values need not be explained. But for a non-idempotent mutation tool whose core concept ('invocation settings' with assistant/user enum values) is undefined, this description is not complete enough for an agent to call it confidently or know the effect of the change.

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 (skillName, setting, value) are documented in the schema itself; the rule sets the baseline at 3. The description adds no meaning beyond the schema — in particular it never clarifies what the 'assistant' vs 'user' setting enum values mean semantically.

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 ('Update invocation settings for a skill') is essentially a restatement of the title 'Update Skill Invocation' with the word 'settings' added. It gives no explanation of what an 'invocation setting' actually controls (the enum values 'assistant'/'user' hint at who may invoke the skill, but this is never stated). It also draws no distinction from the sibling tools skill-display, skill-display-reset-override, or skill-config-set-static-mode.

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

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

There is no guidance on when to use this tool, when not to, or which sibling to prefer. Given siblings like skill-display-reset-override and skill-config-set-static-mode, an agent has no criteria for choosing between them. No guidance is present at all.

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 establish readOnly, idempotent, non-destructive, and closed-world behavior. The description adds important context beyond annotations: directory paths read all files at once, text is returned as text, and binary is returned as embedded base64. It still leaves error or partial-read behavior unstated.

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, each front-loaded and purposeful: purpose, usage trigger, directory behavior, and return format. No redundant or filler content.

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

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

With no output schema, the description usefully explains return formats for text and binary files. It omits some edge cases, such as the empty-path listing behavior, but that is already covered in the schema, so the definition is largely complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both required parameters, including path examples and the empty-path listing behavior. The description's statement about directory paths adds little beyond what the schema already provides, so the baseline of 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 (Read) and resource (files referenced by skill instructions) with examples of file types. It is clear enough to distinguish from skill-config and skill-display siblings, but it never explicitly names or contrasts with the closest sibling, load-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 a concrete trigger: 'Use when skill instructions mention specific files to read or copy.' It also explains the directory-path case, but offers no when-not guidance or sibling alternatives.

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