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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that creating the special `_global` project when missing is allowed, which is useful, but it does not state whether existing projects are overwritten, what filesystem or workspace changes occur, whether permissions are needed, or what happens on conflicts. For a mutating tool, this is a significant transparency gap.

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

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

Two sentences with the primary action front-loaded and the `_global` exception placed second. There is no filler, and both sentences earn their place. The brevity is a structural strength even though it sacrifices completeness 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?

Given the tool's complexity—12 parameters, no annotations, and no schema descriptions—the description is too sparse for an agent to confidently invoke it beyond the simplest case. It does not explain what a project map is, how optional fields relate to the map, or the full significance of `_global`. The output schema reduces the need for return-value documentation, but the input-side context remains inadequate.

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 schema has 12 parameters with 0% description coverage, so the description needed to compensate by explaining the fields. It only mentions 'notes' and never clarifies `working_folder`, `project`, `aka`, `core`, `roles`, `skills`, `include_global`, or the other parameters. This adds almost no semantic value beyond the raw property names.

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

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

The description names a specific action and resource: 'Create a project map' and optional notes. This distinguishes it from the many create_* siblings by identifying the resource as 'project' rather than stanza, skill, or role. However, 'project map' is unexplained domain jargon, so it stops short of full clarity.

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 imperative 'Create' implies this should be used when a new project map is needed, but no explicit when-to-use or when-not-to-use guidance is given relative to siblings like update_project, materialize, or create_stanza. The only usage nuance is the `_global` edge case, which is helpful but not general selection guidance.

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

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

With no annotations, the description carries the full burden. It does disclose some useful behavior: the role is created with no project, and the 'why' parameter affects only the git message. However, it omits other side effects, such as whether an existing role file is overwritten, what permissions are needed, or what the response indicates.

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 deliver the core purpose, a scope constraint, and a key parameter clarification with no wasted words. The most important information is front-loaded.

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

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

The tool has six parameters, no annotations, and no parameter descriptions in the schema. The description explains only 'why' and the no-project scope, leaving key parameters like 'core', 'on_demand', and 'role_id' semantically underspecified. This is not enough for an agent to confidently construct a correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies only the 'why' parameter ('for the git message only'), while the domain-specific meanings of 'core', 'on_demand', and the relationship between 'name' and 'description' remain unexplained. This is insufficient for six parameters.

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 clearly states the action and resource: 'Create a role file.' It adds a distinguishing behavioral fact—'The new role is on no project'—which helps differentiate this creation tool from project-scoped operations and from update/delete role tools.

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

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

There is no explicit guidance on when to use this tool versus alternatives like update_role or create_project. The statement about the new role being on no project hints at scope, but it does not say when this tool is appropriate or when another tool should be chosen instead.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds meaningful details: creating the SKILL.md file, not auto-linking, and optionally writing provenance to skills/<id>.md. It does not mention overwrite behavior or failure cases, but the core side effects are clearly disclosed.

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

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

Two short sentences deliver the essential information with no wasted words. The primary action and path are front-loaded, followed by the important caveat and optional side effect.

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

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

The description covers the main side effects and file path, and an output schema exists to describe return values. However, it lacks guidance on overwriting existing skills, prerequisites, and how to achieve linking if needed. For a create tool with no annotations, this leaves some practical gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies skill_id as the path id and why as the optional provenance trigger, but it does not explain the 'content' or 'description' parameters. These names are somewhat self-explanatory, but the description only partially maps the parameters to their meanings.

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 action and resource: 'Create skills/<id>/SKILL.md'. This clearly distinguishes create_skill from siblings like create_stanza and create_role, and the 'Does not auto-link' note differentiates it from link_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?

The description implies usage context by saying 'Create', but it does not explicitly state when to prefer this tool over alternatives such as update_skill or link_skill. The 'Does not auto-link' note suggests a follow-up linking step, but no explicit when/when-not guidance is provided.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does disclose an extra side effect (why-log entry) and a policy constraint, but it does not explain what 'review policy' means, whether duplicate stanza_id values fail, or whether the operation is reversible. Some behavior is transparent, but important creation semantics are missing.

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 two sentences with no filler. It front-loads the core action, then adds the two most important caveats: no project linking and review policy. Every sentence earns its place.

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

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

For a tool with 7 parameters, 0% schema coverage, and no annotations, the description is too sparse. It leaves critical gaps: what the required parameters mean, what the review policy implies for the caller, and what happens on duplicate stanza_id. The presence of an output schema reduces the need to document return values, but it does not fill the semantic gaps elsewhere.

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

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

Schema description coverage is 0%, so the description must compensate for the 7 undocumented parameters. It only hints at the 'why' parameter via 'append a why-log entry' and does not explain stanza_id, title, description, content, tags, or roles. The parameter names are somewhat self-explanatory, but the description adds little semantic value beyond them.

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

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

The description states a specific verb and resource: 'Create a stanza' and adds a distinguishing side effect ('append a why-log entry'). It also explicitly says what it does not do ('Does not link it to a project'), which separates it clearly from sibling tools like link_stanza.

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

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

The description gives useful usage context: it creates a stanza, does not handle project linking, and is subject to review policy. It does not explicitly name alternatives like link_stanza, but the 'Does not link it to a project' statement gives a clear exclusion and enough context for an agent to route correctly.

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

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

With no annotations, the description carries the full burden, and it does a strong job: it discloses that deletion happens, that preview is the default, that confirm=true bypasses the preview, and that _global is protected. It could additionally state irreversibility or what happens to nested content, but the existing disclosures are substantial for 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 compact and front-loaded with the core action. Every sentence adds relevant safety or usage information, though the phrase 'with the preview's expected' is awkwardly worded and slightly obscure. Minor syntax aside, the structure 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?

The output schema exists, so return-value documentation is covered elsewhere. However, the description omits key parameter semantics and does not clearly define what 'expected' should contain or how preview behaves. For a destructive tool with no annotations, this leaves a few important operational details unresolved.

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

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

Schema description coverage is 0%, so the description must compensate for five undocumented parameters. It only meaningfully touches on confirm and expected ('Preview unless confirm=true with the preview's expected'), leaving project, working_folder, and why unexplained. This is a significant gap for an agent trying to construct valid calls.

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 phrase 'Delete a project directory' uses a specific verb and resource, making the core purpose unmistakable. It is clearly distinguished from sibling delete tools like delete_skill, delete_stanza, and delete_role by targeting 'project directory'. The additional constraint 'Cannot delete _global' further sharpens the tool's scope.

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

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

The description gives explicit when-to-use guidance: 'Do not call unless the user explicitly asked to delete this project.' It also states a clear exclusion—'Findings are not a reason to delete'—which prevents misuse. The preview-confirm behavior adds another layer of usage 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals the preview-by-default mechanism, the confirm flag, and the requirement to pass the preview's expected value. It does not detail side effects or irreversibility, but the deletion preview behavior is well disclosed.

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

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

Three short sentences, each carrying distinct and necessary information: the action, the preview/confirm workflow, and a critical safety guardrail. 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?

The description gives the essential safety-critical workflow and is fairly complete for a DELETION tool with an output schema. However, it leaves the meaning and structure of 'expected' somewhat vague and does not mention the optional 'why' parameter, which could be relevant for audit or justification. There is enough for basic calling but not full parameter comprehension.

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

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

Schema description coverage is 0%, so the description should compensate by explaining parameters. It only hints at confirm and expected through 'Preview unless confirm=true with the preview's expected.' role_id and why are not explained at all, leaving the agent to infer their meaning from the schema alone.

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 the specific verb-resource pair 'Delete a role,' making the tool's core purpose immediately clear. It also clarifies an important behavior—preview by default, delete only with confirm—so it is not confused with a plain destructive delete.

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

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

The description explicitly states when not to call the tool: 'Do not call unless the user explicitly asked to delete this role' and 'Findings are not a reason to delete.' This is strong, unambiguous usage guidance even though no alternative tool is named.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the preview-vs-confirm behavior and warns against unsolicited deletion. However, it does not state whether deletion is permanent, whether related resources are affected, or what happens after a successful delete.

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

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

Two sentences with no fluff; the primary action is front-loaded and the safety constraint follows. The phrase 'with the preview's expected' is somewhat awkward but still concise. It earns its place by conveying the confirm workflow in few words.

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

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

Given the presence of an output schema, return-value documentation is not required. The description covers the core preview-and-confirm flow and the explicit-consent requirement. However, the 'why' parameter is undocumented, and the exact role of 'expected' is under-specified, leaving gaps for an agent trying to construct a correct call.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains confirm ('preview unless confirm=true') and expected ('with the preview's expected'), and skill_id is implied by 'Delete a skill.' However, the 'why' parameter is completely unexplained, and 'expected' remains vague despite being central to the confirmation workflow.

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: 'Delete a skill.' This clearly identifies the operation and distinguishes it from other skill-related siblings like unlink_skill or install_skill. It is clear but does not explicitly differentiate itself from those sibling tools by name.

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

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

The instruction 'Do not call unless the user explicitly asked to delete this skill' provides a strong, explicit condition for when to invoke the tool. It does not mention alternative tools or when not to use it beyond the explicit-consent guard, so it stops short of full routing guidance.

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

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

With no annotations present, the description carries the full behavioral burden. It discloses that the tool previews by default, can delete directly when confirm=true, and requires an expected preview value for confirmation. It also communicates a safety stance about explicit user intent. It does not mention irreversibility, cascading deletion of links, or permission requirements, but the core destructive behavior is reasonably surfaced.

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, each earning its place: the operation, the preview/confirm behavior, and the explicit user-consent rule. The most important safety guidance is front-loaded after the one-line purpose, and there is no filler.

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

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

The output schema exists, so return-value documentation is not the description's burden. The description provides strong safety and workflow context for a destructive operation, but it leaves the 'why' parameter and the precise contract of 'expected' under-specified. For a simple 4-parameter tool, this is close to complete but has a real gap.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to confirm by explaining it bypasses preview, and to expected by tying it to the preview result. However, the required 'why' parameter is not explained at all, and the exact expected-value mechanics remain somewhat cryptic. This is partial compensation, not full.

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: 'Delete a stanza,' which clearly distinguishes it from sibling tools like create_stanza, update_stanza, list_stanzas, and get_stanza. It also adds the conditional preview/confirm behavior, making the tool's core function unmistakable.

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

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

The description gives explicit when-not-to-call guidance: 'Do not call unless the user explicitly asked to delete this stanza. Findings are not a reason to delete.' This is a strong gate that prevents misuse of a destructive tool. It also signals a preview-first workflow unless confirmation is provided.

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

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

With no annotations, the description carries the full burden. It discloses that this is an admin operation, that no map change occurs, and that confirmation relates to refreshing changed bytes. These are useful behavioral hints, but they are fragmentary and do not clarify mutation, failure modes, or prerequisites.

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 very short and front-loaded with 'Admin:', which aids quick scanning. However, the telegraphic fragments ('seed library/<id>/<version>/.', 'No map change.', 'Confirm if refreshing changed bytes.') lack clear sentence structure and omit necessary context.

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

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

For a tool with six parameters, a required pair, zero schema descriptions, and no annotations, the description is far too incomplete. It does not explain the core operation, parameter roles, side effects, or how it fits among the many sibling pack-related tools.

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

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

Schema description coverage is 0%, so the description must compensate for the six parameters. It only indirectly references 'version' and 'confirm'; pack, path, repo, and expected are entirely unexplained. This is a severe gap for an agent selecting and invoking the tool.

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 ('seed') and a resource path ('library/<id>/<version>/'), so it is not a tautology. However, 'seed' is cryptic and the connection to the tool name 'fetch_pack' is unclear, making the purpose only vaguely distinguishable from siblings like get_pack or materialize.

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 'Admin:' prefix hints at restricted usage and 'Confirm if refreshing changed bytes' suggests a confirmation flow, but there is no guidance on when to use this tool versus alternatives. No alternatives or exclusion conditions are mentioned.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It lists output facets but does not state that this is a read-only operation, what failure modes exist, or the meaning of 'versions on disk'.

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 very short and every word contributes information. It is front-loaded with the key scope ('One pack id'), though it is telegraphic and could be structured as a full sentence.

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

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

The tool is simple with one parameter and an output schema, so return structure does not need to be fully explained. However, the absence of usage guidance and behavioral details leaves the description only minimally complete for an agent trying to select it correctly among many pack-related 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 schema only defines 'pack' as a string with no description. The phrase 'One pack id' adds meaning by indicating the parameter is a pack identifier and that exactly one is expected, partially compensating for the 0% schema description 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?

The description clearly identifies what the tool operates on ('One pack id') and what it returns: versions on disk, members, and maps that pin it. It is specific enough to distinguish from list_packs, though it does not explicitly name sibling alternatives.

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 get_pack versus related tools like fetch_pack, list_packs, or where_used. The description gives no context for choosing this tool over alternatives.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Return' clearly signals a read-only operation, and the explicit exclusion of the protocol body is useful behavioral context. It does not mention permission requirements or error behavior, but the simple read-only nature is sufficiently conveyed.

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 one tightly written sentence with no filler. It front-loads the main action and result, then specifies the key exclusion. Every word contributes to the tool's understanding.

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

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

For a simple read-only tool with one parameter and an output schema present, the description is mostly complete: it states what is returned and what is omitted. Minor gaps remain around parameter format and explicit routing to alternative tools for the protocol body, but these are not severe given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It suggests that the sole 'project' parameter identifies which project's data to fetch, adding meaning beyond the bare schema. However, it does not clarify whether the parameter expects a name, ID, or path, leaving some ambiguity.

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 ('Return') and identifies a clear resource: a project's map, notes, roles, and protocol size summary. It explicitly states the protocol body is excluded, which distinguishes it from sibling tools like get_stanza and list_projects.

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 implies the tool should be used when an agent needs project-level summary data without the protocol body. However, it does not explicitly state when to use this tool versus alternatives such as get_stanza or get_role, nor does it name exclusion conditions.

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

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

With no annotations, the description must carry the behavioral burden. 'Return' signals a read-style lookup and the description discloses the returned entities: role file, stanza metadata/sizes, and projects. However, it does not address not-found behavior, permissions, or potential side effects, though the get-oriented wording implies none.

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

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

The description is a single, front-loaded sentence that immediately states the action and the returned data. It contains no filler and each phrase adds distinct information about the tool's output.

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 retrieval tool with an available output schema, the description conveys the essential scope of the result set: role file, stanza metadata/sizes, and projects. It lacks explicit routing guidance versus sibling tools, but the low parameter complexity and output schema reduce the need for further detail.

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 schema has 0% description coverage for role_id, and the description does not explain what role_id should be or how to format it. 'One role file' weakly maps role_id to a role, but the description does not compensate for the missing schema documentation.

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

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

The description names a specific action, 'Return', and a precise resource: one role file along with member stanza metadata and sizes and including projects. This distinguishes it from siblings like list_roles, get_stanza, and get_project, which either list many items or return different resource types.

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

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

The description implies this is for retrieving a single role's full aggregated details, but it does not explicitly state when to prefer it over list_roles, get_stanza, or get_project. The usage context is inferrable from 'one role file' and the role_id parameter, but no direct alternatives or exclusions are mentioned.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does reveal what is returned and that project changes lookup scope, but it omits whether this is a safe read-only operation, what happens on missing skills, permission implications, or how project resolution behaves. This is minimal transparency for a retrieval 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 short and front-loaded with the core operation and return contents. Both sentences contribute useful information, though the second sentence uses vague terminology that could be clearer without adding length.

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 details do not need to be repeated in the description. However, the description is not fully self-sufficient because it leaves skill_id semantics, project behavior, and the meaning of 'map' under-specified, which matters for a tool with no annotations.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It mentions 'project' as optional and links it to pack skills, but it does not explain skill_id, acceptable formats, or the meaning of 'that map's pack skills' well enough for an agent to confidently construct a correct 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 states a specific verb and resource ('Return one skill') and enumerates the returned contents (frontmatter, body, size, payload file list), which helps distinguish it from list_skills and get_pack. The phrase 'that map's pack skills' introduces some ambiguity about what 'map' refers to, preventing a perfect score.

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 explicit when-to-use or when-not-to-use guidance, nor named alternatives. The description implies this is the tool for retrieving a single skill's details, while optional project scoping hints at conditional behavior, but it does not clarify when a sibling like list_skills or get_pack would be more appropriate.

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

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

With no annotations provided, the description carries the full burden. It usefully discloses the ID format ('path relative to stanzas/, no .md') and the optional project's import-traversal behavior. It does not cover not-found or error behavior, but the output schema likely covers return structure.

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

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

Two sentences with no filler. The core action and identifier format are front-loaded, and the optional parameter behavior is succinctly described.

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

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

For a simple getter with two parameters and an output schema, the description covers the essentials: what is returned, how to reference it, and when the optional parameter matters. Some minor ambiguity around 'that map's imports' remains, and it does not address error cases, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does: stanza_id is explained as a path relative to stanzas/ without the .md extension, and project is explained as an optional lookup through that map's imports. Both parameters receive meaningful semantic context beyond the bare schema.

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

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

The description clearly states a specific action ('Return one stanza by id') and resource ('stanza'), with a precise identifier convention. This distinguishes it from sibling tools like list_stanzas, create_stanza, and delete_stanza.

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 makes it clear that this tool is for fetching a single stanza by ID, which is distinct from listing or mutating stanzas. It also explains the optional project parameter's behavior, but it does not explicitly name alternatives or state when not to use this tool.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It indicates a mutating 'set' operation and an admin-only restriction, but it does not mention side effects, whether the previous operator class is overwritten, or any consequences of the change.

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

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

The description is a single front-loaded sentence with no filler. Every word adds information, and the admin-only constraint is placed at the beginning where it is most likely to be noticed.

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

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

The tool has three required parameters and no annotation support, yet the description only partially explains them. An agent still lacks clarity on what 'working_folder' refers to and what behavioral effects setting the operator class has, so the context is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It clarifies 'operator_class' by listing possible values, and implicitly references 'project', but leaves 'working_folder' completely unexplained with no schema help.

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 ('set') with a clear resource ('a project's operator class') and enumerates the allowed values ('admin or bound'). This distinguishes it from sibling tools like revoke or list_roles by targeting a specific assignment 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?

The 'Admin only' prefix gives a useful permission context and the action itself implies when to use the tool, but it does not explicitly state when not to use it or contrast it with alternatives such as revoke or role 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?

No annotations are provided, so the description carries the full disclosure burden. 'Pull onto the shelf' hints at a fetch-or-copy side effect, but the description does not explain whether this is destructive, requires authentication, contacts a remote source, modifies the project, or is idempotent.

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 short, but brevity is not effective here because the core terms are vague and metaphorical. It spends its two sentences on jargon instead of clearly stating the operation, target, and parameters.

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

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

For a tool with four required parameters and no annotations or schema descriptions, this description is not complete enough for reliable tool selection or invocation. An agent still does not know what 'shelf' means, what a 'capability' consists of, or what side effects 'pull onto the shelf' will have.

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

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

Schema description coverage is 0%, and the description only weakly maps to parameters: 'whole pack' suggests pack, 'project' suggests project, 'version or latest' hints at the version parameter, and 'shelf' may relate to working_folder. However, it does not formally define any parameter, acceptable values, or required formats, leaving the agent to guess.

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 offers a rough sense of purpose: a project should use the whole pack at a specified version or 'latest', and the tool 'pulls' it onto a 'shelf'. This weakly distinguishes it from sibling tools like install_stanza and install_skill by focusing on a whole pack, but the action is expressed metaphorically and never explicitly says 'install a capability'.

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 clear guidance on when to use this tool versus alternatives such as install_stanza, install_skill, fetch_pack, or uninstall_capability. The phrase 'if needed' is the only conditional signal, but it does not specify when the need arises or what conditions justify invoking this tool.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does add one useful negative side effect ('Does not copy into native skills/'), but it does not explain whether this mutates the project, rewrites configuration, resolves the pack, or has other important side effects. An install action with no annotation coverage needs more transparency.

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 concise at three sentences with no obvious filler. However, the first sentence is context rather than a clear action, and the metaphor 'Pull onto the shelf' adds ambiguity. It is short but not optimally structured for tool selection.

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

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

For a 5-parameter install tool with no annotations, this is inadequate. It does not explain what 'working_folder' is, what a 'pack' does, when to invoke the tool, or what side effects to expect. The output schema helps with return values, but the description still leaves most of the calling context unspecified.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely maps to project, skill_id, and version via 'This project uses one skill from a pack version'. It does not clarify working_folder or the optional pack parameter, and it never names the parameters explicitly.

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 action is only expressed as 'Pull onto the shelf if needed', which is metaphoorical and does not explicitly say 'install a skill' or name the resource being acted on. It mentions a project, a pack version, and a skill, but the intended operation remains vague and it does not differentiate install_skill from siblings like link_skill or fetch_pack.

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

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

The phrase 'if needed' implies a conditional but gives no concrete criteria for when this tool should be chosen. There is no mention of alternatives such as link_skill, install_capability, or fetch_pack, and no when-not-to-use guidance is provided.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It adds only "if needed" (hinting at conditional/idempotent behavior) and the core/on_demand target distinction, but does not disclose side effects — whether this mutates project state, replaces an existing stanza, requires the pack to be fetched first, or what happens on conflict. For an install/mutation tool this is a significant gap.

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

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

The description is brief at three short sentences, but the "shelf" metaphor costs more clarity than it saves, and the ordering buries the actionable instruction behind a domain statement. It is compact, yet the compactness is achieved at the expense of precision rather than through efficient 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 tool with 6 parameters (4 required), zero annotation coverage, and no parameter documentation, the description is far too thin. It never explains the installation workflow, prerequisites (e.g., whether fetch_pack must run first), behavior of the nullable pack field, or what distinguishes this from install_capability/install_skill. The output schema exists but cannot compensate for missing operational 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 description coverage is 0%, so the description must compensate. It partially explains target ("core or on_demand") and hints at the stanza/version/pack relationship, but leaves working_folder and project entirely unexplained, and does not clarify the nullable pack parameter. Most of the 6 parameters rely on inference from parameter names alone.

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 is cryptic: "This project uses one stanza from a pack version. Pull onto the shelf if needed." It never explicitly states that the tool installs/associates a stanza with a project, and the metaphor "shelf" is undefined. It is less than a pure tautology since it hints at a domain constraint, but an agent cannot determine the actual action being performed with confidence.

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 is given on when to use this tool versus its many siblings (install_capability, install_skill, uninstall_stanza, fetch_pack). The phrase "This project uses one stanza from a pack version" implies a constraint, and "target is core or on_demand" clarifies a parameter, but neither explains selection criteria or conditions that would route an agent here instead of an alternative.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose the key side effect ('Writes now') and a scope boundary ('Does not edit role files'). However, it does not mention duplicate-link behavior, idempotency, prerequisites, or whether the project and skill must already exist.

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

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

Two short sentences with no filler. The first states the core action, and the second provides a valuable side-effect boundary. Both sentences earn their place.

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

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

Despite having an output schema, the lack of annotations and near-zero parameter documentation leaves an agent under-equipped. It is not clear how link_skill differs from install_skill or link_stanza, what working_folder refers to, or what prerequisites must hold before invoking this 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 0% and the description adds little parameter-level meaning. It implicitly maps project and skill_id to the action, but working_folder remains unexplained, and no constraints, formats, or relationships among parameters are provided.

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

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

The description states a specific verb and resource: 'Add a skill to a project's skills list.' This clearly distinguishes the tool from siblings like unlink_skill, create_skill, and install_skill, since the focus is specifically on associating an existing skill with a project.

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 does not explicitly say when to use this tool versus alternatives. The sibling list includes closely related tools such as link_stanza, unlink_skill, and install_skill, but no routing guidance is provided. 'Does not edit role files' is a negative boundary, not a positive usage criterion.

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?

There are no annotations, so the description carries the full behavioral burden. It reveals a useful non-effect ('Does not edit role files') and implies mutation via 'Add,' but it does not state idempotency, duplicate-link behavior, or permission requirements.

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 tight sentences, front-loaded with the action and followed by a valuable caveat. No filler or repetition of schema details.

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

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

The combination of 4 parameters, no annotations, and no parameter descriptions makes this definition only minimally complete. It gives the core operation and target values, but misses prerequisites, identifier meaning, and how working_folder relates to the project.

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

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

With 0% schema description coverage, the description must clarify parameters, but it only maps target to 'core or on-demand list.' working_folder, project, and stanza_id are left to inference from their names, with no format or identifier semantics provided.

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

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

States exactly what it does: adds a stanza to a project's core or on-demand list. The verb 'add' and the resource 'stanza' are specific, and the closing caveat 'Does not edit role files' helps distinguish it from role-related sibling tools.

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

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

Provides a clear use context: adding a stanza to a project's list, plus an explicit exclusion for role files. However, it does not name sibling alternatives such as install_stanza or unlink_stanza, so when-to-use vs. alternatives is only partially addressed.

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

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

No annotations are provided, so the description must communicate safety-relevant behavior. 'List' clearly signals a read-only operation, and the phrase 'associated with a project' scopes the behavior. Still, the description does not mention authorizations, pagination, or any side effects, though for a simple list tool this is not a critical gap.

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

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

One sentence with no redundant words. The verb, resource, scope, and returned fields are all included in a compact, front-loaded 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?

The tool is simple enough that this description is nearly sufficient for invocation: one parameter, a clear scope, and an output schema. However, the description does not clarify what makes these stanzas 'on-demand' or how this list differs from list_stanzas, so an agent may struggle to select the right tool in ambiguous contexts.

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 schema description coverage is 0%, but the description does relate the only parameter to the operation: the stanzas returned are 'associated with a project', which maps project to the scope. It does not specify whether project expects an ID, name, or slug, but the single simple string parameter keeps this ambiguity modest.

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 and resource: 'List on-demand stanzas associated with a project' and even enumerates returned fields. It is clear, but it does not explicitly distinguish itself from the sibling list_stanzas, which could be a source of confusion.

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 phrasing implies the tool should be used when an agent needs on-demand stanzas for a given project. However, there is no explicit when-not-to-use guidance or mention of alternatives such as list_stanzas, so the routing decision is left mostly to inference.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose the returned content scope (pack ids, versions, map usage, unreferenced versions) and implies a read-only inventory, but it does not explicitly state non-destructiveness, pagination, coverage limits, or any side effects.

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

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

The description is extremely tight: 'Shelf inventory' front-loads the gist, followed by a four-item list of what is included. Every word contributes information, and there is no filler.

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

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

Given zero parameters and a present output schema, the description does not need to explain return structure. It covers the key inventory concerns (pack identities, versions, map dependencies, unreferenced versions). The only notable gap is usage guidance relative to pack-focused siblings, which is already penalized under usage_guidelines.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to document about inputs. The baseline of 4 applies, and the description adds semantic value by clarifying what the result covers.

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 identifies the resource (pack ids, versions) and adds distinguishing scope: 'which maps use which, unreferenced versions' — features that separate it from get_pack and fetch_pack. However, it is a noun-phrase fragment rather than an explicit verb+resource statement, and the differentiation from siblings is implicit, not stated.

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

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

No guidance is given for when to use this tool versus siblings like get_pack, fetch_pack, or remove_pack. The phrase 'Shelf inventory' implies an audit/listing purpose, but there is no explicit when-to-use, when-not-to-use, or alternative routing.

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

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

With no annotations, the description carries the safety signal; 'List' implies a read-only query, and the added inclusion details (_global, labels, size summaries) go beyond the bare verb. It does not mention pagination or filtering, but those are not strongly implied for a zero-parameter listing tool, and the output schema can define the return shape.

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 states the action and notable output content with no filler. Every word earns its place and the structure is easy to parse.

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

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

The tool is a simple zero-parameter listing operation, so the description is close to sufficient. The output schema removes the need to describe return values, and the inclusion note helps set expectations. A small gap is the lack of explicit guidance about how this list relates to get_project or project_status, but that is not critical for a low-complexity 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?

This tool has zero parameters, so there is nothing for the description to explain about individual arguments. Schema coverage is 100% because the schema is empty; the description does not need to add 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?

The description names a specific verb ('List') and resource ('projects'), then adds meaningful scope with '_global, labels, and composed-protocol size summaries'. This clearly separates it from singular/write siblings such as get_project or update_project.

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 intended usage is implied by the 'List' verb and the zero-parameter schema, but there is no explicit when-to-use guidance, no alternative named, and no exclusion conditions. An agent must infer that this is the overview/read-all command rather than a more specific project query.

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

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

With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation and the field list indicates response contents, but it does not mention side effects, authentication requirements, pagination, or any other behavioral caveats. It is adequate but not rich.

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

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

A single sentence that front-loads the verb and resource, followed by relevant output fields. Every word earns its place and there is no redundant or vague phrasing.

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

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

For a zero-parameter, read-only listing tool with an output schema, the description is complete enough. It identifies the resource, the fields returned, and the expected side-effect-free nature of the operation. Nothing additional is required for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the schema is fully covered by definition. The description appropriately focuses on output rather than inputs; there is no parameter meaning to add beyond the empty schema.

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

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

The description uses a specific verb ('List') and resource ('role packs') and enumerates the exact fields returned. This clearly distinguishes it from generic list tools like list_packs and list_projects, even without reading their schemas.

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

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

The intended use is implied by 'List role packs,' but the description does not explicitly say when to choose this tool over alternatives like get_role, list_packs, or list_on_demand. There are no exclusion conditions or sibling comparisons.

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

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

With no annotations, the description carries the behavioral burden. 'List' implies a read-only operation and the output fields clarify what is returned. It does not explicitly discuss side effects, filtering, pagination, or ordering, but for a simple list tool this is a modest gap.

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

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

Two short sentences front-load the action and core content. 'Not session start' is an economical caveat but terse to the point of being cryptic; still, there is no 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?

The output schema covers return values and the description states purpose and scope, so basic use is clear. The undocumented prefix parameter and lack of guidance about sibling tools leave gaps for advanced use, but the tool's low complexity keeps the gap moderate.

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 schema has one optional 'prefix' parameter with 0% description coverage, and the description never mentions it. An agent cannot tell whether prefix filters by skill name, project, or something else, so the description fails to compensate for the bare schema.

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

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

The description uses the specific verb 'List' with the resource 'vault skills' and enumerates returned fields (name, description, size, projects). The 'Not session start' caveat narrows scope but doesn't name a sibling tool, so it stops short of full differentiation.

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

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

The first sentence implies use when a general listing of vault skills is needed, and 'Not session start' provides a narrow exclusion. However, no alternatives are named and no conditions explain when to choose this tool over siblings like get_skill or list_on_demand.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates a read-oriented listing action and the fields returned, but it does not describe filtering semantics, ordering, pagination, or whether all accessible stanzas are returned. Basic behavior is clear, but meaningful details are missing.

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

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

The description is a single concise sentence that front-loads the core action and resource, then adds the key filter options. There is no fluff or redundant restating of the schema.

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

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

Given the tool is simple, has no required parameters, and has an output schema, the description covers the main surface. However, because there are no annotations and schema descriptions are absent, the lack of explicit filter semantics and usage distinctions leaves noticeable gaps for an agent deciding how to call this tool correctly.

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

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

Schema description coverage is 0% and the schema only lists property names and defaults, so the description must compensate. The phrase 'Optional prefix, tag, or role filter' identifies all three parameters and marks them optional, but it does not explain what prefix applies to, whether filters combine, or how values are matched. This is not enough detail for confident invocation.

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, 'List stanzas', and then enumerates the returned fields (title, description, tags, roles, size). It clearly distinguishes itself from singular tools like get_stanza and from other list tools by naming the exact resource and output scope.

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

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

The description implies usage as a general listing/browsing tool for stanzas and mentions optional filters, but it does not explicitly state when to choose this over get_stanza, list_projects, list_roles, or other siblings. There is no exclusion or alternative guidance, only an implied read/browse 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?

With no annotations available, the description carries the full burden of behavioral disclosure. It states that files are written, but does not disclose whether existing files are overwritten, what permissions are needed, whether the folder is created, or what side effects beyond writing occur.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes to the core action, target, and destination.

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

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

Despite a small parameter set and an output schema, the description omits crucial context such as why project can be null, what artifacts are actually produced, and when materialize should be invoked in a workflow. An agent could not confidently select or call this tool correctly based on the description alone.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that working_folder is the destination, but it never explains the optional project parameter or what 'configured host adapters' means in relation to parameters.

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 action (write), concrete artifacts (PROTOCOL.md and configured host adapters), and a destination (working folder), so an agent can tell what the tool does. However, it does not explicitly differentiate it from siblings like resolve_protocol or get_stanza, and 'configured host adapters' remains somewhat ambiguous.

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 is provided on when to use this tool versus alternatives such as resolve_protocol, list_stanzas, or install_* operations. An agent must infer the appropriate context from the name and description 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?

No annotations are provided, so the description carries the full burden. The verb 'Inspect' implies read-only behavior and no side effects, which is useful, but the description doesn't cover authorization requirements, failure behavior, or any operational caveats.

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

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

The description is a single, front-loaded sentence with no wasted words. It places the verb 'Inspect' first and then concisely enumerates the three target resources.

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 no-parameter inspection tool with an output schema, the description conveys the essential scope. It lacks usage context or guidance about operator concepts, but the output schema can cover return details and the operation is simple.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to clarify. With no parameters, the baseline is 4 and the description adequately describes what is inspected.

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 the specific verb 'Inspect' and names its resources: operator classes, registered admins, and default class. It is distinct from all sibling tools because none of them target operator-related resources, though it doesn't explicitly name an alternative.

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 is provided about when to use this tool instead of siblings or when it would be inappropriate. The agent is left to infer context from the tool name and description alone.

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

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

With no annotations, the description carries the full beavioral burden, and it explicitly says 'Inspect only', signaling a read-only operation with no mutation. It also discloses the response scope by stating 'No stanza bodies', which sets expectations about what the tool will not return.

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

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

The description is very compact and front-loaded with the core purpose ('Folder inspect card') followed by a tight list of output facets. The cryptic 'card' phrasing is a minor clarity cost, but no sentence is wasteful.

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

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

An output schema exists, so return-value structure is covered, and the parameter set is small. However, missing usage guidance and undocumeted parameter semantics leave an agent without enough context to decide when to call this tool versus its 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?

Schema description coverage is 0% and the description does not explain the optional 'project' parameter, the required 'working_folder', or their relationship. The parameter names are self-explanatory to some degree, but the description adds no semantic value beyond what the schema already shows.

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 ('inspect') and a resource ('folder'), and lists the specific data the tool reports: map, sourced core ids, size, on-demand ids, disk freshness. The explicit 'No stanza bodies' boundary helps distinguish it from sibling stanza-reading tools, though the word 'card' is somewhat cryptic.

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 offers no guidance on when to choose this over the many sibling tools like get_project, list_projects, or list_on_demand. 'Inspect only' implies a read-only context, but no when-to-use or when-not-to-use conditions are provided.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses admin-only authorization, the two-phase preview/confirm workflow, and the destructive removal scope. It does not fully disclose side effects or the role of the 'expected' parameter, but it provides meaningful behavioral context beyond the schema.

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

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

The description is two short, front-loaded sentences. It leads with the critical admin constraint and preview/confirm workflow, then states the action with no filler or redundant restatement of the schema.

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

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

For a destructive admin tool with four undocumented parameters and no annotations, the description is too terse to support fully correct invocation. The preview/confirm flow is implied but the meaning of 'expected', the exact relationship between 'pack' and 'version', and what the preview returns are 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 description coverage is 0%, so the description needed to compensate for all parameters. It vaguely maps to 'version' and 'confirm', and 'an id' likely refers to 'pack', but the required 'pack' value is never explicitly described and the important 'expected' parameter is entirely unexplained.

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 the specific verb 'Remove' and names the resource ('a shelf version' or 'all versions of an id'), making the core action clear. It is distinguishable from sibling tools like list_packs/get_pack, though it does not explicitly name an alternative or contrast itself with another removal tool.

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

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

The description gives clear contextual guidance: this is an Admin-only operation and the caller should preview before confirming. It does not name alternatives or explicit when-not-to-use conditions, but the removal action is fairly unique among the siblings.

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

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

With no annotations, the description carries the full burden. It discloses that the return value has three parts (core bodies, on-demand index, size), which is useful, but it does not mention side effects, error conditions, prerequisites, or whether the operation is read-only. The disclosure is moderate but incomplete.

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

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

The description is a single front-loaded sentence with no filler; each phrase adds information about the return value. It is compact and to the point, though the term 'composed protocol' is unexplained, which slightly reduces clarity.

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

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

The description is too thin for the information an agent needs: the parameter's meaning, the concept of 'composed protocol', when to use this tool versus siblings, and behavior for invalid projects are all missing. An output schema exists but does not compensate for the overall lack of guidance and zero schema parameter coverage.

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

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

Schema description coverage is 0% for the 'project' parameter, and the description only repeats the word 'project' without clarifying whether it expects an ID, name, path, or another identifier. The description fails to compensate for the lack of schema-level documentation.

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

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

The description states a specific verb, 'Return', identifies the resource as 'composed protocol for a project', and lists the output components (core bodies, on-demand index, size). It is clear about the tool's primary purpose, though it does not explicitly differentiate from sibling tools like get_project or list_on_demand.

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

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

Usage context is only implied: if you need a composed protocol, use this tool. There is no mention of alternatives, when not to use it, or required conditions such as an existing project, so guidance is minimal beyond the stated purpose.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the admin-only authorization, the demotion behavior, and a guardrail against removing the last admin. It does not explain reversibility or the meaning of 'default class', but the core side effects are present.

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 two short sentences with no filler. It front-loads the permission requirement and then states the action and limitation, making every clause useful.

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 with an output schema, the description covers the main behavior and a key guardrail, and it makes the admin prerequisite explicit. However, the complete absence of parameter-level guidance means the description is not fully self-contained for an agent without domain knowledge.

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

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

Schema description coverage is 0%, and the description does not explain either `project` or `working_folder` beyond their names. Since both parameters are required strings with no schema descriptions, the agent must infer their meaning entirely from external context, which is a significant gap.

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

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

The description uses a specific verb phrase, 'drop a project back to the default class', which clearly identifies the resource and the outcome. It goes beyond the bare tool name 'revoke' and is distinct from related mutation tools like grant or update_project.

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 an explicit prerequisite ('Admin only') and an explicit when-not condition ('Cannot revoke the last admin'). It does not name alternative tools or contrast with siblings like grant, so it stops short of full routing guidance.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does indicate that the operation is destructive ('Drop') and scoped ('Shelf unchanged'), but it does not explain permanence, required permissions, cascading effects, or what 'whole-capability record' actually entails.

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 extremely short and has no filler; both sentences carry intent, and the side-effect note is front-loaded near the main action. However, the brevity sacrifices clarity, keeping it from a perfect score.

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

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

This is a destructive uninstall-style operation with no annotations, no usable parameter documentation, and only a cryptic two-sentence description. Even though an output schema exists and return values need not be explained, the description still lacks essential context about what a 'map' is, what a 'capability record' represents, and what consequences the operation has.

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

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

Schema description coverage is 0% and the description does not explain any of the four required parameters (working_folder, project, pack, version). The wording 'this map's' is the only implicit hint that project/folder identify the target, which is far too little to compensate for the complete lack of parameter documentation.

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

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

The description uses the verb 'Drop' and identifies a resource ('this map's whole-capability record'), so it gestures at the operation, but 'map' and 'whole-capability record' are unexplained jargon. It does not meaningfully distinguish itself from sibling tools like uninstall_stanza or uninstall_skill beyond the vague 'Shelf unchanged' note.

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 about when to call this tool versus alternatives, no prerequisites, and no exclusions. The phrase 'Shelf unchanged' hints at a boundary but does not tell an agent when this tool is the right choice or when to prefer uninstall_stanza/uninstall_skill.

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

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

With no annotations, the description must carry behavioral disclosure. It does state the primary effect (removing the skill from the import record) and a non-effect ('Shelf unchanged'), which is useful. However, it omits other behavioral traits like reversibility, permissions, or side effects on linked resources.

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 two short sentences with no filler: the main action is front-loaded and the second sentence adds a meaningful scope qualifier. Every word 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?

Despite having an output schema, the overall definition is incomplete for a mutating tool with five required, undocumented parameters and no annotations. It relies heavily on undefined domain jargon like 'this map' and 'Shelf,' and offers no information about prerequisites, failure modes, or the broader uninstall workflow.

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

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

Schema description coverage is 0%, so the description must compensate for the five undocumented required parameters. Phrases like 'this pack skill' and 'this map' only vaguely map to pack, skill_id, project, and working_folder; version is not addressed at all.

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 action ('Drop') and a specific resource ('this pack skill') plus a scope ('this map's import record'). The phrase 'Shelf unchanged' helps distinguish it from deletion-like operations, though it does not explicitly name a sibling tool.

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 choose this tool over alternatives such as unlink_skill, delete_skill, or install_skill. 'Shelf unchanged' implies a contrast, but no explicit when-to-use or when-not-to-use information is provided.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose the key side-effect boundary: the stanza is dropped from the import record and the shelf is unchanged. It does not say whether the action is reversible, whether the installed artifact is removed from disk, or what permission is required.

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

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

Two short sentences with no filler, and the core action is front-loaded before the side-effect note. It is compact, though slightly telegraphic due to unexplained jargon.

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 five required parameters, no annotations, and no param descriptions, this is under-specified. The agent is not told what a map or import record is, how the parameters select the target, or what preconditions exist; only the shelf preservation is disclosed. The output schema can cover returns, but it does not compensate for missing input semantics.

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

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

Schema coverage is 0% and the description adds no explicit parameter meanings. The names working_folder, project, pack, version, and stanza_id are somewhat self-explanatory, but the description never explains how they identify the map, import record, or stanza, so it falls short of compensating for the missing schema descriptions.

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

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

The description uses a specific verb and object: 'Drop this stanza from this map's import record.' This clearly identifies the target resource and scope. It does not explicitly name a sibling alternative, and the term 'map' is domain jargon, so it is not a 5.

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

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

'Shelf unchanged' implies this tool is for removing a stanza from a map while preserving the shared library, giving the agent a usage boundary. However, it never directly states when to prefer this over delete_stanza, unlink_stanza, or uninstall_capability.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Writes now' does signal immediate mutation, which is useful, but the description does not say whether the skill itself is deleted, whether the unlink is reversible, or what side effects occur on the project map. For a mutating operation, this is insufficient.

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 very short and front-loaded, with the operation stated first and no filler. 'Writes now' is a compact but meaningful behavioral note. The brevity is efficient, even though it contributes to incompleteness in other dimensions.

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

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

The tool has an output schema, so return-value documentation is not required, but it still lacks annotation coverage, parameter explanations, and alternative routing. The description tells the agent what the tool does and that it writes, but not enough about prerequisites, side effects, or how the parameters relate to the operation. For a three-parameter mutating tool, this is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate by explaining the parameters, but it does not. None of working_folder, project, or skill_id are described. The parameter names are somewhat suggestive, but an agent still lacks essential meaning such as what working_folder refers to or how skill_id should be formatted.

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, 'Remove', and a specific resource, 'a skill from a project's map', which distinguishes this from related operations like link_skill or delete_skill. It is not a tautology and gives the agent a clear sense of the primary action. It could be slightly sharper about what 'map' means, but the core purpose is discernible.

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 explicit guidance about when to use this tool versus sibling tools such as link_skill, delete_skill, or uninstall_skill. The phrase 'from a project's map' implies a specific relationship, but the description does not state when unlinking is appropriate, when it is not, or what alternative should be chosen instead.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses one negative behavior (does not edit role files) but omits side effects, permissions, reversibility, or what happens to associated resources. This is thin for a mutation tool.

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

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

The description is two short sentences with no filler. Each sentence earns its place: the first states the core operation, the second clarifies a meaningful boundary. It is front-loaded and appropriately sized.

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?

Even though an output schema exists, the description lacks enough context for reliable selection and invocation. There are no usage conditions, no parameter details, no side-effect disclosure, and no explanation of what 'project's map' means. The tool is left ambiguous among many stanza-related 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?

Schema description coverage is 0%, and the description adds no meaning for any of the three parameters: working_folder, project, and stanza_id. The parameter names are somewhat self-explanatory, but the description does not compensate for the complete lack of schema documentation.

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

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

The description states a clear verb and resource: 'Remove a stanza from a project's map.' The additional clause 'Does not edit role files' clarifies scope. However, 'map' is somewhat internal terminology and the tool is not explicitly distinguished from siblings like delete_stanza or uninstall_stanza.

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 is given about when to use this tool versus alternatives such as link_stanza, delete_stanza, or uninstall_stanza. The only hint is 'Does not edit role files,' which implies a boundary but does not state when this tool should be selected.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It usefully reveals that changes are applied immediately ('Attach/detach role writes immediately') and that the response reports members, weight, and affects_projects. It does not mention persistence, rollback, or side effects, but given the output schema exists, this is a reasonable level of disclosure.

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

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

The description is brief and front-loaded with the tool's core purpose in the first sentence. The second sentence is compact but somewhat cryptic ('Attach/detach role writes immediately'), sacrificing clarity for brevity, so it is not a perfect 5.

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

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

This is a high-complexity mutation tool with 16 parameters, no annotations, and no parameter descriptions, yet the description covers only role-related behavior and omits the other fields it can update. It also fails to explain how this relates to sibling tools like create_project, delete_project, or update_role, leaving an agent under-equipped to invoke it correctly across its full parameter surface.

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

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

Schema description coverage is 0%, so the description must compensate for 16 undocumented parameters, but it only hints at role attachments/detachments. Terms like add_core, add_skills, include_global, and remove_on_demand are not explained, and the phrase 'Attach/detach role writes' does not map clearly to the many parameter names.

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

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

The description states a specific verb ('update'), resource ('project map'), and mode ('incrementally'), which distinguishes it from create_project and delete_project at a basic level. However, it does not fully advertise the breadth of writable fields (name, repo, notes, skills, etc.), so differentiation from sibling update_role/update_skill is only 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?

The phrase 'incrementally update' implies the intended use for partial modifications, but the description gives no explicit guidance on when to prefer this over create_project, delete_project, or update_role. It also provides no prerequisites such as requiring an existing project or a particular working_folder 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently reveals the critical two-phase behavior: member changes are preview-only unless confirm=true with the expected payload. This is genuinely useful behavioral information, though it does not cover permissions, failure cases, or expected-object details.

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 only two sentences and front-loads the core purpose. Every clause earns its place: the write-now behavior and the preview/confirm exception are both stated without fluff.

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 10-parameter tool with no annotations and no parameter descriptions, the description captures the central workflow but omits several details an agent may need: what 'expected' should actually contain, how the preview is obtained, the difference between core and on-demand members, and the purpose of role_id/why. The presence of an output schema partially compensates, but the input semantics are not fully self-contained.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to name, description, the four member add/remove parameters, confirm, and expected by explaining their relationship. However, it does not address role_id or why, and it does not distinguish core members from on-demand members, leaving important semantics implicit.

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, 'Update a role,' which clearly distinguishes it from create_role, delete_role, get_role, and list_roles. It also narrows the update scope by separating write-now fields (name/description) from previewed member changes, so an agent knows exactly what this tool operates on.

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

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

The description gives clear context for how to use the tool: name and description changes write immediately, while member add/remove changes remain in preview unless confirm=true and the preview's expected value is supplied. It does not explicitly state when not to use this tool or name alternatives like create_role, but the intended usage is clear enough.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context by noting the update surfaces where_used and affects_projects, implying cross-project impact. However, it does not disclose mutability consequences, permission requirements, or reversibility, so coverage is only partial.

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 short, front-loaded, and stays focused on what the tool updates. The second sentence is somewhat vague, but it still adds useful side-effect information without wasting words.

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

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

For a mutation tool with no annotations and low schema coverage, the description is too sparse. It does not clarify which fields belong to frontmatter versus body, what 'why' is for, how where_used is surfaced, or what preconditions apply. The presence of an output schema helps but does not cover these semantic gaps.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It hints that 'frontmatter' relates to metadata such as description and 'body' to content, but it never explicitly maps the four parameters (skill_id, description, content, why) or explains the purpose of 'why'. Too much is left to inference.

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 ('Update') and a precise resource ('SKILL.md frontmatter and/or body'), making it clear this modifies existing skill content. It broadly distinguishes itself from sibling create/delete/get/list skill tools, though it does not explicitly name an alternative.

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 is given about when to use this tool versus get_skill, create_skill, or delete_skill. It does not mention prerequisites such as the skill needing to exist or when a user should choose this over alternatives.

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

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

The description discloses behaviors beyond the schema: a mandatory why-log side effect, a 'where_used' return, and subjection to a review policy. These are valuable operational traits an agent cannot derive from the input schema. There is no annotation coverage, so the description must carry the burden of transparency, and it does a solid job for an update 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?

A single sentence that front-loads the primary action (Update a stanza), then adds the immediate side effects and policy constraint. Every clause earns its place, and it is information-dense without being bloated.

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 where_used return is adequately grounded. However, the review policy is vague: an agent does not know when updates get reviewed, what happens on rejection, or whether some fields (roles/tags) have additional constraints. Given seven parameters, zero schema descriptions, and no annotations, the description leaves meaningful operational gaps.

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

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

Schema description coverage is 0%, so all seven parameters are functionally undocumented by both schema and description. However, the parameter names are self-explanatory: stanza_id, why, tags, roles, title, content, description. The description does not explain the required 'why' semantics beyond 'why-log entry', but it does hint that 'why' matters. This is a modest value-add, not a complete compensation for zero schema 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?

The description states a specific verb and resource ('Update a stanza') and adds two clear side effects ('append a why-log entry', 'return where_used'). This clearly distinguishes the tool from CREATE/DELETE siblings and even from GET/LIST tools, because the description names the unique return value of where_used.

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 implies when to use it: when you need to modify an existing stanza and record a why-log reason. However, it gives no explicit exclusion like 'use create_stanza for new stanzas' or 'use update_skill for skills.' The review policy hint is present but not expanded into actionable guidance, such as what conditions trigger review or how to handle rejected updates.

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

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

With no annotations, the description carries the full behavioral burden and does a good job: it discloses that the operation is read-only unless fix=true, distinguishes issues from findings, and specifies that fixes never consume findings. The cryptic "review dial" reference prevents a higher score.

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 deliver purpose, safety, and semantic distinctions with no filler. The phrase "Vault health check" is front-loaded, and each subsequent sentence adds behavioral value.

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 tool with an output schema, the description covers the key aspects: purpose, safety, fix semantics, and result interpretation. The undefined "review dial" and lack of alternative-tool guidance leave small gaps, but nothing essential for invoking the 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?

The schema provides only a bare boolean named fix with zero description coverage. The description compensates by explaining that fix=true enables fixes and that default behavior is read-only, adding meaning beyond the schema. More detail on what fixes actually do would be stronger.

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?

"Vault health check" names a clear resource and operation, distinguishing validate from the CRUD and status tools among the siblings. A more explicit verb such as "run" or "perform" would strengthen it, but the intent is unambiguous.

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

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

The phrase "Vault health check" implies when the tool should be used, and "Read-only unless fix=true" hints at how to choose the default mode. However, it never states when to prefer this over alternatives or when fix=true should be set, leaving usage partly implicit.

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

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

With no annotations, the description must carry behavioral context. It discloses that the tool lists referencing files and implies a read-only search operation, but it does not state permissions, limitations, or behavior when no references exist. Some useful context is present, but the disclosure is not comprehensive.

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

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

The description is a single concise sentence that front-loads the core action and scope. There is no filler, and every word contributes to the 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 simple one-parameter listing tool with an output schema, the description covers the essential purpose and scope. It is slightly under-specified regarding permissions and edge-case behavior, but the presence of an output schema reduces the need to document return values.

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 schema only says stanza_id is a string, and schema description coverage is 0%. The description adds meaning by indicating that this parameter identifies the stanza whose references are sought, but it does not explain the expected format, source, or how to obtain a valid stanza_id. It partially compensates for the schema gap.

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

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

The description states a specific action ('List') and resource ('project map and role file') and specifies the search object ('a stanza'). It clearly conveys what the tool does and implicitly differentiates it from the sibling where_used_skill by targeting stanzas rather than skills, though it does not name that sibling explicitly.

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

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

The intended use case is implied: use this tool when you need to find project maps and role files that reference a given stanza. However, the description does not explicitly state when to prefer this tool over alternatives such as where_used_skill, nor does it provide any exclusion conditions.

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

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

With no annotations, the description carries the transparency burden. 'List' implies a read-only operation and 'Roles never appear' is a useful output-behavior disclosure, but there is no mention of auth requirements, errors, or side-effect safety beyond the implication of 'list.'

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 two short sentences with no filler. The main action is front-loaded and the second sentence provides a meaningful exclusion without bloating the text.

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

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

For a simple one-parameter listing tool with an output schema, the description covers the core behavior and an important output exclusion. It could use more guidance about when to choose this tool over siblings, but it is largely complete for straightforward invocation.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the skill_id parameter. It only says 'this skill,' which adds little beyond the parameter name and does not clarify format, origin, or constraints.

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

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

The description clearly states the verb and resource: it lists project maps that include the given skill. It also adds a useful boundary with 'Roles never appear,' but it does not explicitly distinguish itself from sibling tools like where_used.

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

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

The phrase 'Roles never appear' implies a boundary and hints that this tool is not for role-related lookup, but there is no explicit when-to-use or alternative recommendation. The usage context is only implied, not stated.

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