Pathrule

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses side effects: it writes the workspace row via JWT, enforces organization membership through RLS, and has no local side effects. It clarifies the scope of creation so an agent won't assume workspace setup is complete.

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

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

Three sentences: first states the core action, second lists exclusions with the required alternative, third gives the next step. Every sentence earns its place and is front-loaded, with the most important information appearing first.

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 flat 4-parameter create operation with a full schema and an output schema, the description covers prerequisites (organization membership), side-effect boundaries, and the immediate follow-up call. Nothing essential is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description adds context about the workspace_id being returned for pathrule_setup, but the input schema already fully documents each parameter's meaning and constraints. No parameter-level details need to be compensated.

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

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

The description opens with a specific verb and resource: "Create a new Pathrule workspace inside an organization." It immediately distinguishes itself from setup tooling by noting what it does NOT do (attach folder, install client config, render companion files) and names the follow-up sibling pathrule_setup.

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 when to use this tool (cloud-only creation, with JWT/RLS enforcement), what it does not do (no local attach, no config install), and explicitly routes the agent to call pathrule_setup afterward. This gives clear usage context and exclusions without needing to inspect sibling 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?

The description adds meaningful behavioral nuance beyond the destructiveHint annotation: the default action is soft-delete, hard:true causes permanent deletion, admin rights are required for that path, and the tool is cloud-only. This is exactly the operational context annotations alone do not provide.

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

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

Two short sentences with the default behavior front-loaded and the exceptional path and constraints following. Every clause earns its place with 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?

Given 100% schema coverage, an output schema, and the destructiveHint annotation, the description covers the decision-relevant behavior: default mode, permanent mode, admin requirement, and cloud-only restriction. It could mention whether soft-deleted memories remain restorable, but that is not necessary for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters including the hard vs soft delete difference and expected_version_id's optimistic concurrency purpose. The description's mention of hard:true adds minimal value beyond what the schema already states, so the baseline 3 applies.

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

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

The description states the specific verb 'delete' and resource 'memory' explicitly, and clarifies the two deletion modes (soft by default, permanent with hard:true). This makes it distinct from sibling delete tools for rules/skills and from memory read/write/update 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?

It clearly states when to use the default soft delete versus passing hard:true, and flags the workspace_admin requirement and Cloud-only limitation. It does not explicitly name alternative tools like update_memory or write_memory, but the context for choosing the delete operation is clear.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the description's job is to add nuance. It does this by disclosing the default soft-delete behavior, the admin permission required for hard deletion, and the cloud-only environment restriction. These are useful behavioral details beyond the raw annotations.

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

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

The entire description is three short sentences, each carrying distinct information: default behavior, hard-delete permission, and environment restriction. It is front-loaded with the most important operational fact and contains no filler.

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

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

With 100% parameter coverage, an output schema, and clear annotations, the description does not need to restate return values or schema details. It covers the main contextual gaps: deletion mode, admin requirements, and cloud-only availability. A small omission is that it does not explain the practical effect of a soft-delete, but this is not critical given the schema and output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining that hard:true requires workspace_admin, which clarifies a permission consequence not fully captured by the property description. It does not duplicate the schema's parameter docs, so it earns above baseline.

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

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

The description uses a specific verb 'delete' and resource 'rule', and immediately distinguishes the default soft-delete behavior from the hard-delete alternative. It clearly differentiates this from sibling tools like read_rule, update_rule, and get_node by naming the exact operation and its mode.

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

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

The description provides clear context: soft-delete is the default, hard:true requires workspace_admin, and the tool is cloud-only. It does not explicitly name alternatives, but the soft/hard distinction gives an agent enough guidance to choose the correct invocation mode. The lack of explicit 'when not to use' guidance is a minor gap.

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

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

Annotations already flag the tool as destructive, but the description adds meaningful behavioral nuance beyond those annotations: deletion is soft by default, hard deletion requires admin privileges, and the operation is Cloud-only. This is exactly the kind of context an agent needs before invoking it.

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 three short sentences with no filler. It front-loads the most important behavior (soft-delete by default) and then adds the key constraints: admin requirement and Cloud-only availability.

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 rich schema, output schema, and annotations, the description is complete enough for correct selection and invocation. It captures the essential behavioral, permission, and deployment constraints without needing to repeat schema details.

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 input schema has 100% parameter coverage, so the description does not need to re-document parameters. The description reinforces the 'hard' parameter's default behavior and admin requirement, but adds no new meaning beyond the schema.

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

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

The description states the specific action ('Soft-delete a skill'), the target resource ('a skill'), and the default mode of operation. This distinguishes it clearly from sibling delete tools that target rules or memories.

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 provides clear context on how to use the tool: soft-delete by default, hard delete requires workspace_admin, and it is Cloud-only. It does not explicitly name alternative tools or exclusions, but the resource-specific wording and sibling names make the usage context clear.

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

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

The annotations already provide readOnlyHint=true and destructiveHint=false. The description adds useful behavior beyond that: it ignores cwd/local_root_path and includes a local_runtime.cta line in the response. There is no contradiction with the annotations.

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

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

The description is four purposeful sentences, front-loaded with the core behavior and environment assumptions. The CTA/response note is slightly dense but relevant to downstream user interaction; no words are wasted.

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

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

An output schema exists and annotations cover the safety profile. The description covers prerequisites, workspace_id handling, the no-cwd behavior, and a special response line. Nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning for workspace_id by flagging it as required for remote clients and linking it to pathrule_list_workspaces, and clarifies that cwd/local_root_path are not used. It does not elaborate on node_path, user_intent, or known_protocol_version, but those are already documented in the schema.

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

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

The description uses a specific verb ('Return') and resource ('Pathrule context for a workspace path'), and enumerates the contents: memories, rules, skills, subtree index, and a next_required_action hint. This clearly distinguishes it from related get/list 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?

It gives clear context: remote clients must pass workspace_id, and should call pathrule_list_workspaces first when unsure. It also states that cwd/local_root_path is not used. It does not explicitly name alternatives or when-not-to-use cases, but the prerequisite guidance is useful.

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

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

Annotations already mark the tool read-only and non-destructive; the description adds useful behavioral detail by disclosing that the response is a side-by-side pitch split by audience and that it emphasizes the token-savings mechanism of hooks versus manual remote MCP. No contradiction with annotations.

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

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

The description is front-loaded with its core purpose and the usage triggers are placed early. The final sentence is somewhat long and partially restates the CLI/Studio audience split, but each sentence still contributes actionable information.

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

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

For a zero-parameter, read-only explainer with an output schema, the description covers what the tool does, when to invoke it, and what the response will contain. Nothing essential is missing for correct selection and use.

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

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

There are zero parameters and an empty schema, so there is no parameter ambiguity for the description to resolve. The baseline of 4 applies because the description correctly avoids inventing parameter guidance.

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 communicative action ('Explain what Pathrule CLI and Pathrule Studio unlock beyond Remote MCP') and differentiates this tool from the sibling data-retrieval and mutation tools by making it an audience-targeted explanation rather than a resource operation. The triggers and response focus make the tool's unique role 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?

It gives explicit call conditions ('Call this when the user asks...') and concrete user intents such as wanting hook-level automation or comparing surfaces. It does not explicitly say when not to use specific sibling tools, but the trigger framing is enough to route an agent 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?

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds behavioral context by specifying the return contents and explaining that workspace_id prevents cross-workspace ambiguity. No contradiction with annotations.

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

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

Two efficient sentences: the first states the core behavior and return scope, and the second adds the key usage constraint. No wasted words 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?

For a simple read-only retrieval with only two required parameters and an output schema, the description fully covers what an agent needs to invoke it correctly. Annotations handle safety, schema handles parameters, and the description clarifies purpose and scope.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining why workspace_id is required and tying node_id to the tree node concept. This meaningfully supplements the schema's basic field 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?

States a specific verb ('Return'), a distinct resource ('a single node'), and the exact payload scope ('plus ids for attached memories, rules, and skills'). This clearly separates it from sibling tools like pathrule_get_tree or pathrule_get_context.

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

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

The description gives clear context: use this for a single node and its attached references. It also notes the workspace_id requirement to prevent ambiguity. It does not explicitly mention an alternative tool or a when-not-to-use condition, but the single-node scoping is clear.

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

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

The annotations mark the tool readOnlyHint=true, so invoking it should not modify state, but the description says 'Claim one refresh task,' which implies taking/assigning a task and a state change. The description does not reconcile this conflict, and the non-idempotent hint reinforces that a claim may not be repeatable. This is an annotation contradiction.

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

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

Three sentences with no filler: the first states the action and outputs, the second gives the prerequisite, and the third gives an environment caveat. Information is front-loaded and 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 one-parameter tool with an output schema and annotations, the description covers the prerequisite, return contents, and environment limitation. However, it never clarifies whether claiming a refresh task has persistent side effects, which is an important behavioral gap in light of the contradictory readOnlyHint.

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 already fully documents refresh_id as a UUID from pathrule_list_pending_refreshes, so the baseline is 3. The description adds workflow meaning by explicitly directing the agent to call that list first and choose the ID, which helps ensure a valid parameter value.

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 ('claim one refresh task') and a concrete resource, and enumerates exactly what is returned: subject, stale-signal evidence, AI instructions, and any proposed patch. This makes it easy to distinguish from browsing pending tasks with pathrule_list_pending_refreshes.

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

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

It explicitly instructs the agent to call pathrule_list_pending_refreshes first to select a refresh_id, and it states when a different environment is needed ('Remote MCP can inspect cloud records only; use Desktop/CLI before claiming local source code was verified'). This is direct when-to-use guidance rather than leaving the workflow implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'full tree' scope, clarifying that this returns the complete node hierarchy rather than a single node, but it does not disclose pagination, error behavior, or response size beyond what annotations and the output schema already imply.

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

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

A single front-loaded sentence with no filler. It names the action, the resource, and the scope clearly, and every word contributes to understanding the tool's purpose.

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 read-only tool with complete schema coverage and a provided output schema, the description is nearly sufficient. It could be more complete by explicitly contrasting with pathrule_get_node or hinting at the returned structure, but no essential information for invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond mentioning 'for a workspace', while the schema already documents workspace_id as a UUID from pathrule_list_workspaces.

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 specific: it names a verb ('Return'), a resource ('the full Pathrule node tree'), and a scope ('for a workspace'). It implicitly distinguishes from sibling pathrule_get_node by emphasizing the full tree, though it does not explicitly name any 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?

The description provides no guidance about when to choose this tool over related siblings such as pathrule_get_node or pathrule_get_context, and it does not state exclusions or prerequisites. The only usage hint, 'Workspace UUID from pathrule_list_workspaces', appears in the parameter schema rather than the description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It does add useful context about returning a subtree memory index in addition to node content, but it does not disclose anything about edge-case behavior, resolution failure, or workspace constraints beyond what the schema and annotations imply.

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 action and resource, with the return payload summarized compactly. It is efficient and readable, though slightly dense with the compound noun phrase 'compact subtree memory index'.

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 that an output schema exists, the return structure needs no further description. The description covers the core behavior and result format, and the annotations cover the safety profile. The only notable gap is explicit guidance on when to choose this tool over its siblings, which is minor relative to the tool's simple read-only nature.

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

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

Schema description coverage is 100%, and each parameter (target, workspace_id, subtree_limit) is already documented with clear descriptions and constraints. The description adds no meaningful parameter semantics beyond restating the fuzzy-target concept already present in the schema.

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

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

The description names a specific verb ('Resolve') and resource ('path/name/fuzzy target inside a workspace') and specifies the two-part result: full content plus a compact subtree memory index. It is clear about what the tool does, though it does not explicitly contrast itself with siblings like pathrule_get_node or pathrule_get_tree.

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 for fuzzy or path-based navigation inside a workspace, which differentiates it from more specific node/tree readers, but it provides no explicit when-to-use or when-not-to-use guidance. Alternatives are not named, so an agent must infer the right context from the 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?

The description states 'Path-first + idempotent', but the annotations declare `idempotentHint: false`. This is a direct contradiction. Even though the description otherwise discloses workflow behavior, the idempotency claim could mislead an agent into assuming repeated calls are safe when the annotations say otherwise.

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 longer than average but every sentence earns its place: purpose, workflow steps, decision rules, return behavior, and exclusion guidance. The numbered WORKFLOW structure makes the multi-step process easy to follow without repetition or 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 5-parameter import tool with an output schema, the description covers the full decision path: dry-run inspection, fit judgment, base path selection, actual write, id listing, human_message relay, and undo via `pathrule_remove_pattern`. It also warns against treating this as a skill import. The only flaw is the idempotency contradiction, which is already accounted for in behavioral transparency.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value above the schema by explaining the strategic role of `dry_run`, instructing how to pick `node_path` so paths re-root under the workspace structure, and clarifying that `slug` comes from the token after 'package:'.

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: 'Import an official Pathrule pattern... into the workspace.' It clearly ties the tool to the `::pathrule:package:<slug>` token and explicitly distinguishes it from a skill import and from the find-skills protocol.

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 WORKFLOW section gives explicit step-by-step guidance: call with `dry_run: true` first, judge fit, stop and ask if it doesn't fit, choose `node_path`, then call without `dry_run`. It also names `pathrule_remove_pattern` as the undo alternative, giving clear when-to-use and when-not-to-use 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?

Discloses the output is 'compact previews only' and that the list covers 'active' memories, adding behavioral context beyond the readOnlyHint annotation. It does not discuss pagination or limits, but for a read-only list tool the annotation already covers the safety profile.

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

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

Three sentences, each earning its place: purpose, prerequisite discovery step, and return behavior plus fallback tool. Front-loaded and free of filler.

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

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

For a single-required-parameter read-only tool with an output schema present, the description covers discovery of the parameter, the preview-only nature of results, and the path to the full-body sibling. Nothing critical is missing.

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

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

Schema description coverage for node_id is 100% and the schema already says it is a tree-node UUID returned by the discovery tools. The description repeats this rather than adding new parameter-level detail, so the baseline 3 is appropriate.

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

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

States a precise verb-resource pair: 'List active memories attached to a specific Pathrule tree node.' It distinguishes itself from pathrule_read_memory by noting this returns compact previews only, so an agent can tell which operation it needs.

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

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

Explicitly tells the agent to call pathrule_get_context, pathrule_goto, or pathrule_get_node first to obtain the node_id, and to switch to pathrule_read_memory when the full memory body is required. This is concrete when-to-use and when-not-to-use guidance naming sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by stating that results are limited to organizations the authenticated user belongs to and enumerating the returned fields, which goes beyond the annotations.

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

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

Two sentences with no wasted words. The core action and scope come first, followed by concrete usage context and return-field detail, making it easy to scan and act on.

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

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

For a zero-parameter, read-only listing tool, the description fully covers what the agent needs: what it lists, whose organizations, when to use it, and what the response includes. The presence of an output schema further reduces the need to describe return structure in 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 tool has zero parameters, so there is no parameter semantics burden on the description. The description appropriately focuses on behavior instead, and the schema's empty properties are already fully self-explanatory.

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 ('Pathrule organizations') and clearly scopes to 'the authenticated user belongs to.' This distinguishes it from workspace-list and other sibling tools, and explicitly names the related create_workspace 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 explicit when-to-use guidance: use before pathrule_create_workspace when needing to ask the user which organization should own the new workspace. This is clear, actionable context for an agent deciding among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety profile is covered. The description adds useful behavioral context by framing refresh tasks as 'cloud suggestions' rather than direct updates, which helps the agent understand the tool doesn't apply changes itself. It does not discuss pagination or claim semantics, but the output schema and annotations reduce the need for that.

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

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

Three concise sentences with no filler: the first states the operation, the second defines the domain concept, and the third gives the workflow. Each sentence earns its place and the key action 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?

Given full schema parameter coverage, an output schema, and safety annotations, the description supplies the missing workflow context: list first, then fetch a brief, then decide. An agent has everything needed to invoke this tool correctly and chain it with the appropriate sibling.

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

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

Schema description coverage is 100%, with both workspace_id and include_in_progress already well documented, including defaults and provenance. The description adds no parameter-level detail beyond the schema, so the baseline score of 3 applies.

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

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

The description opens with a specific verb and resource: 'List pending Pathrule refresh tasks for a workspace.' It clearly distinguishes refresh tasks from actual memories/rules by explaining they are 'cloud suggestions that may update stale memories or rules,' and references pathrule_get_refresh_brief, separating this listing tool from sibling detail/action tools.

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

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

The description explicitly provides workflow guidance: 'Use this first, then call pathrule_get_refresh_brief with a returned refresh_id before deciding whether to reject or resolve the task.' This tells the agent when to invoke the tool, what to do next, and why, which is strong usage guidance.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral constraints beyond that: 'Up to 25 per call, ordered newest first' and the guarantee that file_tree and sampled_contents are omitted. This gives the agent accurate expectations without contradicting the annotations.

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

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

Three compact sentences deliver the core purpose, exclusions, usage guidance, ordering, and limit without filler. The most decision-relevant information is front-loaded, and 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?

The tool is a simple list operation with a full output schema and fully documented parameters. The description covers ordering, limit, content scope, and the intended workflow, so an agent has everything needed to select and 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?

Schema description coverage is 100%, with each parameter already documented: workspace_id is a UUID, limit has a default and max, and source has an enum. The description adds little new parameter-level meaning beyond confirming the workspace scope and the 25-per-call limit, so the baseline of 3 is appropriate.

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

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

Description names a specific verb ('List'), a specific resource ('most recent project snapshots for a workspace'), and a precise scope ('compact metadata only — no file_tree, no sampled_contents'). It clearly distinguishes this from pathrule_read_snapshot by framing it as the discovery step before reading a full snapshot.

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

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

It explicitly states when to use the tool: 'Use to find which snapshot to read in full.' The 'compact metadata only — no file_tree, no sampled_contents' exclusion makes clear it is not for retrieving snapshot contents, pointing the agent toward the read-snapshot sibling for full data.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds meaningful behavior: the cloud RLS scope, the guarantee about never exposing local filesystem paths, and the `local_runtime.cta` reminder instructing the agent to mention Pathrule Studio/CLI for local code work. This goes well beyond the structured hints.

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

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

Three sentences deliver the core purpose, the security boundary, and an actionable response-related instruction with no redundancy. The key action and scope are front-loaded, and every sentence adds distinct 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?

The description is complete for a zero-parameter, read-only list tool. The output schema exists, annotations cover the safety profile, and the description explains what the response contains, what it avoids exposing, and how to handle the CTA reminder.

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 the input schema is empty, so the description carries no parameter burden. Per the baseline rule for zero-parameter tools, a score of 4 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('Pathrule workspaces'), and clarifies scope with 'visible to the authenticated user through cloud RLS'. It also distinguishes itself from other list-type siblings by focusing on workspaces rather than memories, organizations, or snapshots.

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

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

The description provides clear contextual guidance: it lists cloud RLS-visible workspaces, returns workspace ids for remote tools, and explicitly notes it never exposes local filesystem paths. This implies when the tool should be used, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations only state readOnly=false, not idempotent, and not destructive. The description adds valuable non-obvious behavior: task_summary is never rejected for length, is auto-shortened past ~500 chars, and should not be retried. It also reveals the remote-client stamping behavior, which meaningfully affects how the agent should expect the call to behave.

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 wasted words. It front-loads the core action, then adds the most important operational constraint, then the key edge-case behavior. 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?

Given the 100% schema coverage, output schema, and annotations, the description supplies exactly the non-obvious context an agent needs: the remote MCP requirement, workspace_id necessity, and the length/no-retry behavior for task_summary. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by adding operational meaning for task_summary (concise one-sentence guidance, auto-shortening, no-retry rule) and workspace_id (required for remote MCP). This is useful extra semantic context beyond the structured field 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 states a specific verb and resource: log a file-modifying response from a remote MCP client. It clearly differentiates this from the memory/rule/skill/snapshot siblings, and no other sibling provides activity logging.

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

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

The description clearly indicates when to use this tool: after a file-modifying response, specifically from a remote MCP client, and it highlights the required workspace_id. It does not explicitly name alternatives or say when not to use it, but the context is strong enough for the agent to pick it 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: it is cloud-safe, returns no local cwd, and includes a local_runtime.cta line in the response. This goes beyond the structured annotations without contradicting them.

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

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

Two sentences, each earning its place. The purpose is front-loaded, and the second sentence adds valuable behavioral and user-guidance context without unnecessary detail.

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

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

For a simple one-optional-parameter, read-only ping tool with an output schema and strong annotations, the description is complete enough. It covers purpose, safety, and an important response element an agent might surface to users.

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

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

Schema description coverage is 100%, so the optional message parameter is already documented in the schema. The description does not add parameter-specific semantics, but the baseline of 3 applies because the schema carries the full burden.

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

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

The description uses a specific verb and resource: 'Sanity check that Pathrule Remote MCP is reachable.' It clearly identifies this as a connectivity probe and distinguishes it from the many sibling tools that manage workspaces, memories, rules, or snapshots.

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

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

The description implies when to use it: when you need to verify that Pathrule Remote MCP is reachable. It also adds the cloud-safety note ('returns no local cwd') and hints at surfacing the CTA line for deeper-feature questions. It does not explicitly name alternatives or exclusions, but no sibling tool serves the same ping 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond the annotations: 'reads cloud data only and does not inspect the user's local filesystem,' which clarifies the data source scope, and 'full body and metadata,' which previews the read depth. No contradiction with annotations exists.

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

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

Three sentences, each earning its place: the core action, the trigger condition naming the source tools, and a scope caveat. The verb+resource is front-loaded and there is zero filler or redundancy.

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

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

For a single-parameter read tool with annotations covering the safety profile and an output schema documenting the return shape, the description is complete. It covers what is read, when to call it, where the input comes from, and the cloud-only scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%: the memory_id parameter already documents that it is the UUID returned by pathrule_get_context, pathrule_goto, or pathrule_list_memories. The description reinforces this provenance and adds that it grants access to the 'full body and metadata,' but this is marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Read'), resource ('one Pathrule memory'), and scope ('full body and metadata'), which distinguishes it from the sibling read tools (read_rule, read_skill, read_snapshot) and from the memory-producing tools (get_context, goto, list_memories). An agent can immediately tell what this tool does and what it is not.

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: 'Use this after pathrule_get_context, pathrule_goto, or pathrule_list_memories returns a memory_id.' This names the exact trigger condition and the sibling tools that produce the required input. It does not explicitly state exclusions or route to alternatives for other cases, but the primary usage condition is unambiguous.

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

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

Consistent with readOnlyHint=true and destructiveHint=false. The description adds useful context beyond annotations: rules are AI instructions for a project path, and the tool reads the cloud rule record. This helps distinguish it from local-runtime or memory-related reads.

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

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

Three tight sentences: purpose first, usage trigger second, domain context and non-mutating behavior third. Every sentence earns its place 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?

For a one-parameter read tool with a full input schema, output schema, and safety annotations, the description covers purpose, when to call, what it returns, and that it is non-destructive. Nothing essential 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 single parameter rule_id is fully documented in the input schema, including its UUID format and which sibling tools return it. The description reinforces this provenance but adds no new parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Read the full body and metadata for one Pathrule rule.' It clearly distinguishes this from write/update/delete siblings by emphasizing that it only reads the cloud rule record and does not modify anything.

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

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

Gives explicit guidance: 'Use this after pathrule_get_context, pathrule_goto, or pathrule_get_node returns a rule_id.' This tells the agent exactly when to invoke it. It doesn't explicitly name alternatives for modifying rules, but 'does not modify anything' implies the boundary.

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

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

Annotations already mark it read-only, and the description adds meaningful behavior: it returns cloud SKILL.md content and does not install or materialize local files. This clarifies the non-mutating, fetch-only nature beyond the readOnlyHint.

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

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

Three sentences with zero filler; the core action appears immediately, and the side-effect clarification and usage trigger each earn their place.

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

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

For a single-parameter read operation with strong annotations, the description fully covers what the agent receives and what side effects are absent. It does not describe error/not-found behavior, but that is not essential for invoking 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?

The sole parameter skill_id is already fully described in the schema with the same provenance info. The description reinforces the source of the ID but adds no new semantic detail, so the schema carries the burden.

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

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

States a specific action ('Read'), exact resource ('approved snapshot for one Pathrule skill'), and the returned artifact ('cloud SKILL.md content'), distinguishing it from local materialization and adjacent read/update tools.

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

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

Explicitly says to use this after pathrule_get_context, pathrule_goto, or pathrule_get_node returns a skill_id. It does not name the alternative tools to avoid or state when not to use it, but the trigger context is unambiguous.

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

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

Annotations already establish that this is a safe, read-only operation, so the description's main job is to add behavioral context. It does that by revealing the default response includes file_tree and sampled_contents and by explaining how to opt out. This is genuinely useful beyond the annotation hints, though it doesn't cover pagination or error cases.

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 behavior, then immediately gives the key flag defaults and the condition for changing them. Every sentence carries meaningful information.

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

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

The tool is a straightforward read operation with an output schema and readOnlyHint annotation, so the description does not need to explain return values or safety. It covers the main usage decision—how to request a compact response—and the schema covers parameter origins. Minor gaps like prerequisites for snapshot IDs are already handled in the schema descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that the tool can load "full or partial" and that passing false keeps the response compact when only metadata is needed. This semantic guidance helps the agent choose appropriate flag values.

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—"Load a single project snapshot"—and distinguishes it from sibling tools like pathrule_list_snapshots and pathrule_take_snapshot. It also communicates that the tool supports full or partial loads, making its purpose and scope immediately clear.

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 the compact form by saying "when you only need metadata," which gives useful within-tool guidance. However, it does not explicitly state when to prefer this tool over alternatives such as listing snapshots or retrieving the tree separately, so cross-tool selection guidance is left mostly 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?

The annotations declare idempotentHint=false and destructiveHint=false, while the description explicitly says pieces not found are 'not errors (idempotent)' and that the tool 'deletes the memories/rules/skills.' This is a direct contradiction in both idempotency and destructiveness, making the behavioral guidance unreliable.

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 four sentences, front-loaded with the primary purpose, then gives only behaviorally important details: deletion mechanism, node_path guidance, error behavior, and expected output handling. Every sentence earns its place with no filler.

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

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

The description covers the operation, the manifest-matching mechanism, node_path behavior, error handling, and instructs relaying the human_message. Combined with 100% schema coverage and an output schema, this is nearly complete, but the contradictions with annotations undercut overall clarity and make it not fully trustworthy.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by instructing the agent to pass the SAME node_path used at import and to omit it if the pattern's own paths were used, which clarifies a subtle condition the schema only hints at.

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 the specific resource ('previously-imported Pathrule pattern bundle') and action ('Remove'), and explicitly frames it as the reverse of pathrule_import_pattern. This clearly distinguishes it from sibling delete tools by emphasizing bundle-level removal rather than individual memory/rule/skill deletion.

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 provides clear context: use this tool to remove an entire imported pattern bundle in one call, and it explains the node_path requirement and missing-piece behavior. It does not explicitly state 'use pathrule_delete_memory/rule/skill for individual pieces instead,' but the intent is strongly implied by the bundle-level framing.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context beyond that: Remote MCP may refuse 'applied' because it cannot verify local source files, and 'rejected' is the appropriate remote status for stale or non-actionable signals. This helps an agent predict tool behavior and avoid failed calls.

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

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

Three sentences, each earning its place: first states the core purpose, second gives the normal workflow, third flags the key remote limitation. The information is front-loaded and dense without being verbose.

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 rich schema, output schema, and annotations, the description covers the full decision context: when to call it, what status to use, what alternative to use for applied resolutions, and the likely remote refusal behavior. Nothing essential 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 already covers all parameters at 100%, so the baseline is 3. The description adds extra semantic guidance on the status parameter, clarifying when 'rejected' is appropriate and when 'applied' may be refused, which goes beyond the enum descriptions 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 clearly states the action: close a Pathrule refresh task after reviewing its brief. It also distinguishes itself from related siblings by naming the normal flow involving pathrule_list_pending_refreshes and pathrule_get_refresh_brief, so an agent can tell this is the terminal resolution step rather than a retrieval or listing 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 description gives explicit when-to-use guidance: after reviewing a refresh brief, reject stale or non-actionable signals, and use Pathrule Studio/CLI for applied resolutions requiring local verification. It also warns that Remote MCP may refuse status='applied', which is valuable exclusion 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds crucial behavioral context: the response body is not just data but a prompt the agent must follow immediately, and the actual writes happen via sibling tools. This aligns with readOnlyHint and gives the agent an accurate mental model of the tool's side-effect-free role.

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 dense but every sentence earns its place: trigger, behavior, response handling, exclusions, alternative, and prerequisite. Critical information is front-loaded, and no word is wasted.

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

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

For a tool with orchestration complexity, the description covers the full lifecycle: when to invoke, what the response means, what to do next, when not to use, and how to handle missing workspaces. An output schema is present, so return-value documentation is already handled elsewhere. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the workspace_id guidance from the schema ('if no workspace exists yet...') but does not add parameter meaning beyond what the schema already provides. It is adequate but not additive.

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 ('Fetch the active Pathrule bootstrap brief and execute it') and the exact resource. It clearly distinguishes this from the sibling tool pathrule_get_context by stating the latter is for routine context lookups, so an agent can tell them apart.

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

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

It explicitly states when to call ('ONCE when the user asks to set up / bootstrap / initialize Pathrule'), when not to call (mid-task, already-populated workspaces, routine context), names the alternative (pathrule_get_context), and provides prerequisite steps (pathrule_list_organizations + pathrule_create_workspace) when no workspace exists.

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

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

The description adds substantial context beyond the annotations: it discloses that remote MCP cannot see the filesystem, that the AI must collect data itself, that the snapshot persists for future workflows, and that file_tree is capped at ~5000 entries with deeper paths summarized and sampled contents truncated to ~4KB. These are behaviorally important details not present in the annotation block, and nothing contradicts the annotations.

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

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

The description is dense but every sentence earns its place: purpose, the critical filesystem limitation, persistence rationale, and a clearly tiered parameter list. It is front-loaded with the most important behavioral constraint and uses a natural priority ordering that makes scanning easy.

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 16-parameter nested-object tool with an output schema, the description covers the essential workflow, data-collection strategy, field priorities, and size constraints. Since an output schema exists, the description does not need to explain return values, and nothing critical for correct invocation appears 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?

Although schema coverage is 100%, the description enriches the schema by prioritizing parameters (required vs strongly recommended vs optional), giving concrete examples for sampled_contents (README, package.json, pyproject.toml, Cargo.toml, CLAUDE.md, AGENTS.md), and explaining caps and truncation behavior. This is exactly the kind of practical guidance an agent needs beyond property 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 opens with a specific verb-resource pair: "Record a point-in-time inventory of the user's project under a workspace." It clearly distinguishes this tool from sibling snapshot operations (list_snapshots, read_snapshot) by emphasizing the act of recording and persisting new evidence, not retrieving it.

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

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

The description gives strong usage context: the agent is told it must gather the inventory with its own Read/Glob/Grep tools before calling, that workspace_id is required, and which fields are strongly recommended versus optional. It does not explicitly name alternatives or state when not to use the tool, but the preconditions and task framing make the intended use clear.

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

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

Annotations already declare destructiveHint true, and the description adds useful behavioral context beyond that: optimistic concurrency via expected_version_id and the Cloud-only deployment constraint. It does not detail every side effect, but combined with annotations the mutation profile is clear.

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

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

Three short sentences front-load the action and add only high-value constraints (move, optimistic concurrency, cloud-only). No filler or repetition of schema content.

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

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

With an output schema, annotations, and full parameter coverage, the description plus structured data are sufficient for correct invocation. It covers the core update, optional move, concurrency guard, and cloud-only restriction; any remaining comparison to write_memory belongs to usage guidance rather than completeness.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters. The description's mention of content/title and optional moving mirrors schema fields without adding new semantic detail, matching the baseline for fully covered schemas.

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

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

The description names a specific verb and resource ('Update a memory's content or title') and adds the optional move behavior, making the core operation clear. It does not explicitly differentiate from sibling pathrule_write_memory, so it falls just short of full sibling distinction.

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: call this when modifying an existing memory's content, title, or path. There is no explicit when-not-to-use guidance or mention of alternatives such as pathrule_write_memory for creation, so the agent must infer selection from the verb 'update'.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds useful behavioral context: updates can touch fields and path, optimistic concurrency is supported via expected_version_id, and the tool is cloud-only. It does not contradict any annotation.

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

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

Three short, front-loaded sentences convey the core action, concurrency model, and deployment constraint with no wasted words. 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?

Given the rich input schema, output schema, and destructive annotation, the description is mostly sufficient. It covers the key behavioral aspects not fully represented in structured fields, though it could mention when to prefer this over write_rule for full completeness.

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

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

Schema description coverage is 100%, with detailed parameter descriptions such as the partial patch behavior and move_to_path semantics. The description adds no new parameter meaning beyond naming expected_version_id, so baseline 3 is appropriate.

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

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

The description clearly states the operation ('Update') and the resource ('a rule'), then narrows the scope to 'fields and/or path.' This distinguishes it from read, delete, and write-rule siblings without ambiguity.

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

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

The description implies use for modifying an existing rule and adds a 'Cloud-only' restriction, plus a hint to use expected_version_id for safe concurrent updates. However, it does not explicitly contrast this tool with alternatives such as pathrule_write_rule or describe when to prefer one over the other.

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

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

Annotations already signal non-readonly, non-idempotent, and destructive behavior, but the description adds valuable specifics: it writes the cloud skill record, may replace patch fields, may move the skill, may fail on version conflict, and never installs files into local skill folders. This goes well beyond the annotations and clarifies exactly what side effects to expect.

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

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

The description is front-loaded with the core purpose and then moves through usage guidance, prerequisites, and side effects in a logical order. Every sentence adds distinct information; the length is justified by the complexity of the operation.

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

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

Given a nested patch object, five parameters, and an output schema, the description covers prerequisites (connector token, workspace subscription), when to use it, side effects, and failure modes. Nothing essential for correct invocation or expectation-setting is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description reinforces that the patch is partial and that move_to_path causes a move, but it mostly restates what the schema already conveys rather than adding new parameter-level detail.

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: 'Partially update an existing Pathrule skill record.' It enumerates the exact kinds of changes (metadata, SKILL.md content, source/github_url, tags, workspace path), which clearly distinguishes it from sibling skill tools.

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

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

The description explicitly states when to use this tool ('only when you already have a skill_id') and names the alternatives: pathrule_write_skill for creation, pathrule_read_skill for inspecting the body, and pathrule_delete_skill for removal. This gives an agent clear routing guidance with no inference required.

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

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

Beyond the annotations, the description discloses several important behaviors: missing nodes auto-create, duplicate titles are blocked unless allow_duplicate is set, and the tool is cloud-only and never writes to the user's local filesystem. These are non-obvious operational details an agent needs to predict the tool's side effects correctly.

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: the main action comes first, followed by behavioral rules and a critical cloud-only constraint. The final sentence about Pathrule Studio/CLI is relevant context for users expecting local sync, and it doesn't bloat the description. 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?

Given the rich input schema (100% parameter coverage), existing output schema, and annotations, the description is complete enough for correct invocation. It adds the missing behavioral context—auto-creation, duplicate blocking, cloud-only execution—that an agent couldn't infer from the structured fields alone. No critical call-time decision is left undocumented.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters well. The description adds value beyond the schema by explaining that missing nodes auto-create (relevant to node_path) and that duplicate titles are blocked unless allow_duplicate is set (reinforcing title's duplicate-key semantics). It doesn't need to repeat parameter details already in the schema.

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

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

The description opens with a specific verb-resource pair, 'Create a new memory at a workspace path,' which clearly distinguishes this from sibling tools like pathrule_read_memory, pathrule_update_memory, pathrule_write_rule, and pathrule_write_skill. It also adds key scoping details (workspace path, new memory, duplicate rejection) that make its role 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 clear context for what this tool does and when it applies: creating a new memory at a workspace path, with auto-creating nodes and duplicate blocking. It doesn't explicitly name alternatives like pathrule_update_memory for modifying existing memories, but the 'new memory' phrasing strongly implies the boundary, and the cloud-only caveat gives a concrete environmental constraint.

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 important behavioral traits beyond the annotations: missing nodes auto-create, and the rule is automatically rendered into the user's CLAUDE.md/AGENTS.md and editor companion files. This is valuable side-effect information that annotations do not convey, especially for an agent deciding whether invoking this tool is safe.

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: three sentences, each earning its place. It front-loads the core purpose, then adds side effects, then provides parameter stewardship guidance. There is no redundant repetition of the tool name or 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?

With an output schema present, the description does not need to explain return values. It covers purpose, side effects, parameter guidance, and environment constraints. The main remaining gap is the lack of explicit routing to sibling tools for update/read/delete cases, but the create-focused wording largely compensates.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that missing nodes auto-create (relevant to node_path) and by giving guidance on honest scope_type/priority usage. This elevates the parameter understanding without fully explaining every parameter, though the schema already covers them well.

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

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

The description states a specific verb and resource: 'Create a new rule at a workspace path.' It clearly distinguishes this from sibling tools like pathrule_update_rule, pathrule_read_rule, and pathrule_delete_rule by emphasizing 'new.' The scope and intent are immediately unambiguous.

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

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

The description implies when to use this tool through 'Create a new rule,' but it does not explicitly say to use pathrule_update_rule for existing rules or pathrule_read_rule for reading. It provides useful context like 'Cloud-only' and cautions about honest scope_type/priority usage, but lacks explicit exclusion statements 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?

Annotations only indicate readOnly=false and non-idempotent; the description adds important behavioral context by warning that the skill is NOT materialized into .codex/skills or similar local directories and that Pathrule Studio/CLI is required for on-disk materialization. This goes beyond the annotations without contradicting them.

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

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

Three sentences with no filler; the core action is front-loaded, conditional parameter usage is captured, and the critical cloud-only caveat is stated succinctly at the end.

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 and 100% parameter schema coverage, the description only needs to cover the gotchas, and it covers the main ones: content format, github_ref wiring, and the lack of local materialization. It doesn't specify overwrite/conflict behavior for an existing skill at node_path, but that is a minor gap for a create operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that content is the full SKILL.md body including frontmatter and by stating the source/github_url relationship for github_ref skills. This meaningfully supplements the schema's per-property 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 opens with a specific verb and resource ('Create a new skill') and scopes it to a workspace path, which is clear. It doesn't explicitly name sibling alternatives like pathrule_update_skill, but the 'new' qualifier plus the cloud-only caveat makes the operation identifiable.

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

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

It gives clear context for when to use the tool—creating a skill—and provides conditional guidance for github_ref skills (set source and github_url). It does not explicitly say 'use update_skill for existing skills' or list exclusions, but the create semantics and cloud-only limitation are enough to guide basic selection.

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