Pathrule

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

Discloses write operation via JWT, security model (RLS), and side-effect boundaries (no local attachment/config). Annotations provide only basic flags, but the description adds rich behavioral context beyond 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, each with distinct purpose: statement of action, list of exclusions, and next step. No wasted words; highly efficient.

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

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

Covers purpose, behavioral constraints, security, and next steps. Lacks discussion of return values beyond workspace_id and error conditions, but sufficient for a creation tool with good schema coverage.

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

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

Schema already provides full parameter descriptions (100% coverage). The tool description does not further elaborate on parameter semantics beyond implying workspace name context. Baseline score 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?

Clearly states it creates a Pathrule workspace inside an organization. Explicitly lists what it does NOT do (attach folder, install config, render companion files), distinguishing it from related tools like pathrule_setup and desktop/CLI processes.

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

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

Provides context (cloud-only, JWT-based, RLS enforcement) and an explicit next-step instruction to call pathrule_setup. Lacks explicit 'when to avoid' usage, but the context is sufficient for an agent to decide.

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 destructiveHint annotation, the description details that default is soft-delete, hard delete requires admin, and the tool is cloud-only. This adds valuable behavioral context not in 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, no waste. Front-loaded with the key default behavior. Every word adds 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?

Covers default behavior, hard delete option, permissions, and cloud-only limitation. Schema already covers expected_version_id. No output schema needed. Missing explicit mention of recovery from soft-delete but not critical for a delete tool.

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

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

Input schema has 100% coverage with detailed descriptions of each parameter. The description adds minimal extra meaning (e.g., default soft-delete) beyond what the schema already provides. 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?

Clearly states it soft-deletes a memory and offers a hard-delete option. Distinguishes from sibling tools like pathrule_delete_rule and pathrule_delete_skill by specifying 'memory' and the default behavior.

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

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

Provides clear context: when to delete a memory, soft vs hard delete, and admin requirement for hard delete. Lacks explicit 'when not to use' or alternatives, but the resource-specific name and sibling tools imply appropriate use.

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 reveals default soft-delete behavior and admin requirements beyond the annotations (destructiveHint=true), adding useful context.

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

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

The description is a single concise sentence that front-loads the key default behavior, with no wasted words.

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

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

The description covers the essential behavioral aspects (soft vs hard delete, admin requirement, cloud-only) and is complete enough given the lack of 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?

With 100% schema coverage, baseline is 3, but the description adds meaning by explaining the hard parameter's effect and expected_version_id's role as an optimistic concurrency token.

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 ('soft-delete a rule') and the resource ('rule'), distinguishing it from sibling tools like pathrule_delete_memory and pathrule_delete_skill.

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

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

The description provides usage guidance by noting that hard deletion requires workspace_admin and is cloud-only, though it does not explicitly contrast with other delete 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 discloses soft-delete default, hard delete requiring admin, and cloud-only restriction. This adds value beyond annotations which only indicate destructive hint. 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 a single sentence that covers the essential information without redundancy. Every word adds value, making it highly efficient.

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

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

Given no output schema, the description does not need to detail return values. It includes the key system constraint (cloud-only). However, it omits whether the operation is synchronous and the expected response, leaving minor gaps.

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

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

Schema covers all parameters with descriptions. The description adds clarifying context about the hard parameter's default and admin requirement, and the cloud-only constraint, complementing 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 clearly states the tool deletes a skill, with two modes (soft/hard) and an admin requirement. It distinguishes from sibling delete tools targeting different resources.

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 explains the soft-delete default and hard delete condition, but does not explicitly state when to use this tool versus alternatives like read_skill or update_skill. However, the purpose is self-evident for a delete operation.

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 that no cwd or local_root_path is used and mentions a specific line in the response. However, it does not discuss authentication requirements, rate limits, or potential side effects beyond what annotations cover.

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 sentences: the first lists return components, the second gives usage guidance, the third mentions a specific response line. It is relatively concise, though the third sentence could be slightly tighter. Still, it is efficient and front-loaded with 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?

Given no output schema, the description enumerates return components (memories, rules, skills, subtree index, next_required_action hint) and mentions a cta line. However, it does not describe the structure or format of the response, nor how to interpret next_required_action. For a tool with 4 parameters, this is adequate but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats some parameter details (node_path defaults to '/', workspace_id required) but does not add significant meaning beyond what the schema already provides. The instruction to pass cached protocol_version is 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 clearly states it returns Pathrule context for a workspace path, listing specific components (memories, rules, skills, subtree index, next_required_action hint). It distinguishes from sibling tools like pathrule_get_node and pathrule_get_tree by its specific purpose.

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 explicit guidance: remote clients must pass workspace_id, and to call pathrule_list_workspaces first when unsure. It implies that you should not use this tool without a workspace_id, but does not explicitly contrast with other tools or mention 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?

Description discloses that the tool splits the pitch by audience and explains the token-savings angle of hooks firing before AI tool calls. Annotations already show readOnlyHint=true, and the description adds meaningful behavioral context beyond 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?

Description is somewhat long (3 sentences) but front-loaded with purpose and usage. Every sentence adds value; minor room for tightening without losing key context.

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

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

Given no output schema and no parameters, the description sufficiently explains the response behavior (audience-split pitch and token-savings angle). Complete for an informational tool with simple inputs.

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 no parameters (schema coverage 100% empty). Baseline for 0 parameters is 4; the description does not need to add parameter info and appropriately omits it.

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

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

The description clearly states the tool's purpose: to explain what Pathrule CLI and Desktop unlock beyond Remote MCP. It uses a specific verb ('explain') and distinguishes itself from sibling CRUD tools by being informational.

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 lists when to call the tool: when the user asks 'is there a better way?', 'why do I need to install something?', wants hook-level automation, or wants to compare surfaces. Provides clear context for use.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return includes IDs for memories, rules, and skills, and warns about workspace ambiguity. No contradictions.

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

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

Two sentences, front-loaded with the main purpose, no extraneous words. Efficient and clear.

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 operation with annotations and high schema coverage, the description completely covers what the agent needs: what it returns and a key constraint. No output schema needed.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds context that workspace_id prevents ambiguity, providing extra 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 clearly states the tool returns a single node plus IDs for attached items. It is specific and distinguishes from siblings like 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 notes the requirement for workspace_id to prevent cross-workspace ambiguity, providing clear context for when to use. It doesn't explicitly exclude alternatives but gives sufficient 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 description states 'Claim one refresh task', implying state modification, but the annotations declare readOnlyHint=true, indicating no state change. This is a direct contradiction that undermines transparency.

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

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

The description is two sentences: first states purpose and output, second provides usage guidance. No wasted words; front-loaded with the essential action.

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?

Although the description covers key aspects (usage, output) and the tool is simple (1 param), the contradiction with annotations creates confusion about behavior. Without an output schema, the description's listed fields are helpful, but the contradiction reduces overall completeness.

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

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

The schema covers the single parameter with a clear description ('Refresh task UUID from pathrule_list_pending_refreshes'). The description adds value by reiterating the prerequisite step, reinforcing understanding 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 clearly states the tool's verb ('Claim') and resource ('refresh task'), and lists specific return fields (subject, stale-signal evidence, AI instructions, proposed patch). It distinguishes from the sibling 'pathrule_list_pending_refreshes' by prescribing it as a prerequisite.

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 instructs to call 'pathrule_list_pending_refreshes' first to select a refresh_id, and warns about the limitation of remote MCP vs Desktop/CLI. It provides clear context for when to use but lacks explicit when-not-to-use or direct alternatives.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds minimal extra behavioral context. It could mention potential performance considerations for large trees, but not required given simple nature.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It effectively conveys the essential 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 straightforward read operation with one parameter and no output schema, the description is largely complete. It could be enhanced by briefly stating the return format (e.g., hierarchical tree), but not required.

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

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

Schema coverage is 100%, and the parameter is well-defined. The description does not add any additional meaning beyond the schema's description of workspace_id.

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 (Return), the resource (full Pathrule node tree), and the scope (for a workspace). It effectively distinguishes from sibling tools like pathrule_get_node, pathrule_list_workspaces, etc.

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 lacks any guidance on when to use this tool versus alternatives. It does not mention explicit context or exclusions, such as preferring get_node for individual nodes.

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 indicate it is read-only (readOnlyHint=true) and non-destructive. The description adds that it returns full content and a subtree memory index, but does not disclose any additional behavioral traits such as performance implications, required permissions, or the format of the subtree index. Given the annotations, the bar is lower, and the description adds minimal context beyond them.

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

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

The description is a single sentence that front-loads the action and result. Every word is necessary—no filler, unnecessary details, or repetition. It is clear and efficient.

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

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

Given the tool has 3 parameters and no output schema, the description provides a reasonably complete picture: it resolves a fuzzy target, returns full content for the node, and adds a compact subtree memory index. However, it could be more explicit about the structure of the subtree index and the exact meaning of 'fuzzy target' to fully cover the missing output schema documentation.

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 67% (2 of 3 parameters have descriptions). The description does not add any information about the parameters beyond what the schema already provides; notably, the 'subtree_limit' parameter is not mentioned in the description. The description compensates partially by explaining the tool's overall function but not the parameter semantics.

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

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

The description uses strong verbs 'Resolve' and 'return' to clearly state the tool's action. It specifies the resource as 'a path/name/fuzzy target inside a workspace' and distinguishes itself from sibling tools like pathrule_get_node by mentioning fuzzy matching and returning a 'compact subtree memory index', which is unique.

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 when the target is a path, name, or fuzzy input, but it does not explicitly state when to use this tool over alternatives like pathrule_get_node or pathrule_get_tree. No exclusions or comparisons are provided, leaving usage context somewhat vague.

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 indicate readOnlyHint=true and destructiveHint=false. Description adds that it returns compact previews only and that the operation is non-destructive. No contradictions.

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

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

Two sentences, front-loaded with purpose, no redundant information. Efficient and clear.

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 prerequisites, return type (previews), and next steps. Lacks mention of pagination or limits, but for a simple list tool this is sufficient given no 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 covers 100% of parameters. Description adds value by explaining how to obtain the node_id (via pathrule_get_node, etc.), which is not in the schema description.

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 tool lists active memories attached to a specific tree node. It distinguishes from sibling tools like pathrule_read_memory (full body) and pathrule_write_memory (write).

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 instructs to use discovery tools first for node_id, and directs to pathrule_read_memory for full body. Provides clear when-to-use and when-not-to-use 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 indicate readOnlyHint=true, so the read-only behavior is expected. The description adds value by listing the exact return fields (id, name, slug, plan, subscription_status, role), which is beyond what annotations 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?

The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It is concise without being under-specified.

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 no parameters and a simple list operation, the description is complete. It explains the return fields even though there is no output schema, providing sufficient context for an agent.

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 no parameters, so schema coverage is 100%. The description adds no extra parameter info (none needed), but it does list return fields, which provides context 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 clearly states it lists organizations the user belongs to, using specific verb 'List' and resource 'Pathrule organizations'. It distinguishes itself from sibling tools by explicitly mentioning it is used before pathrule_create_workspace.

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 explicit guidance: use this tool before pathrule_create_workspace when needing to ask the user which organization the new workspace should live under. This clearly indicates when and why to use this tool.

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

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

Annotations already indicate readOnlyHint=true, and the description adds context that refresh tasks are 'cloud suggestions that may update stale memories or rules,' which is valuable behavioral information 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?

The description is only three sentences, front-loaded with the action, and every sentence adds value: purpose, concept explanation, and next step. No wasted words.

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

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

Given the tool's simplicity, full schema coverage, and annotations, the description is complete. It explains refresh tasks and the workflow. A minor gap might be lack of pagination info, but it's not critical for this tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description does not add extra parameter-level meaning, thus 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 action (list), resource (pending refresh tasks), and scope (for a workspace). It distinguishes itself from the sibling pathrule_get_refresh_brief by outlining the workflow.

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 tells the agent to use this tool first and then call pathrule_get_refresh_brief, providing clear next steps. However, it does not mention when not to use this tool or consider alternatives.

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

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

Annotations already set readOnlyHint=true. Description adds what is excluded (no file_tree, sampled_contents) and constraints (up to 25, newest first). No 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?

Two concise sentences, no fluff. Front-loaded with main action and key constraints.

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 listing tool with 3 params and no output schema, description provides sufficient context: what is returned (metadata only, not full snapshot), pagination, ordering. Could benefit from mentioning response fields or pagination beyond limit.

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?

Description implicitly covers workspace_id and limit, but does not mention source filter. Schema covers some parameter details (67% coverage). Description adds minimal extra meaning beyond 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?

Description states specific verb 'List' and resource 'project snapshots for a workspace', distinguishes from reading full snapshot. Contradicts no sibling.

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

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

Explicitly says 'Use to find which snapshot to read in full', implying use this before pathrule_read_snapshot. Mentions limit and ordering, but could elaborate on when not to use.

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 indicate readOnly=true. The description adds key behavioral details: uses cloud RLS, never exposes local paths, and response includes a specific reminder. No 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 concise sentences, each delivering purposeful information: purpose, security constraint, and response behavior. Front-loaded with the core action.

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

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

Given zero parameters and no output schema, the description covers all necessary context: scope, security, and a notable response element. Complete for the tool's simple function.

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?

No parameters exist, so schema coverage is 100%. The description does not need to elaborate on parameters, but it adds value through other behavioral context.

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 tool lists Pathrule workspaces visible via cloud RLS, specifically for remote tools, and never exposes local paths. This distinguishes it from siblings like list_organizations or list_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?

Implies use for obtaining workspace IDs for remote tools, with a security note about not exposing local filesystem paths. Also mentions a CTA for local work, providing context, but does not explicitly state when not to use.

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 are all false, providing little behavioral guidance. The description adds that the tool stamps 'ai_client="cloud-connector"', indicating a side effect. However, it does not disclose other traits like whether the log is persisted, if it can fail silently, or any rate limits. Given the minimal annotation coverage, the description adds some but not enough context for full transparency.

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

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

The description is two sentences long, directly stating purpose and a key requirement. No redundant or extraneous information. Every sentence adds 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?

Given 9 parameters (6 required), a nested object (files_touched), and no output schema, the description is insufficient. It fails to explain the purpose of most parameters, the expected return behavior, or error conditions. The tool logs a file-modifying response, but the complexity of the input schema demands more detail 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 only 11% (only workspace_id has a description). The description itself only mentions workspace_id and the fact that it is required. It does not explain the meaning of other parameters like scope, action, domain, subjects, task_summary, files_touched, or the nested structure. The description does not compensate for the low schema coverage.

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

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

The description clearly states the tool logs a file-modifying response from a remote MCP client, specifying the action 'log' and the resource type. The verb 'Log' and the object 'file-modifying response' are specific and distinct from sibling tools which are CRUD, read, list, etc.

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 a usage condition: 'Remote MCP requires workspace_id and stamps ai_client="cloud-connector".' This tells the agent when to use the tool (for logging from remote MCP) and a necessary prerequisite. It implicitly excludes other contexts but does not explicitly name alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds behavioral context like being a 'sanity check' and not returning local cwd. It does not contradict annotations and provides useful supplementary information.

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 concise sentences, front-loaded with the primary purpose. Every sentence adds value without 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?

The description mentions the response includes a cta line, which is helpful given the lack of an output schema. For a simple ping tool, this is sufficient context, though it could also note the response format more explicitly.

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

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

The schema has 100% description coverage for the single optional 'message' parameter, so the description's role is minimal. The description does not explain the parameter beyond what the schema provides, which is acceptable at baseline level 3.

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 tool's purpose as a sanity check for connectivity to Pathrule Remote MCP, using specific verb 'ping' and resource 'Pathrule Remote MCP'. It distinguishes itself from siblings, none of which serve a similar connectivity-checking role.

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 mentions 'Cloud-safe: returns no local cwd', guiding the agent on when to use this tool safely. It also hints at additional usage by noting the cta line in the response. While no alternative tools are mentioned, the sibling list lacks any similar ping-like tool, so this is acceptable.

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 that it reads 'cloud data only and does not inspect the user's local filesystem,' which is valuable context 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 concise sentences. The first sentence clearly states the purpose, and the second provides usage guidance. No unnecessary words 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 one simple parameter, clear annotations, and no output schema, the description fully covers what the agent needs: what the tool does, when to use it, and what to pass in.

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

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

Schema coverage is 100% and describes the parameter format. The description adds value by explaining where the memory_id comes from (returned by three sibling tools), which helps agents understand how to obtain the required input.

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 ('Read') and identifies the resource ('full body and metadata for one Pathrule memory'). It also distinguishes from sibling tools that return lists or context, making the tool's purpose 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?

Explicitly states when to use this tool: 'Use this after pathrule_get_context, pathrule_goto, or pathrule_list_memories returns a memory_id.' Also clarifies that it does not inspect the local filesystem, helping agents choose alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description's statement 'does not modify anything' is consistent but adds no new behavioral insight. However, it adds context that it reads 'full body and metadata' and that it operates on a 'cloud rule record,' which provides useful detail 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?

Three concise sentences: first states purpose, second gives usage guidance, third adds context. Front-loaded with essential information, no unnecessary words.

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

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

For a simple read tool with no output schema, the description covers purpose, usage, and side effects. It could be more specific about the return format, but 'full body and metadata' is adequate given the tool's simplicity and the annotations covering safety.

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 describes the rule_id parameter with a good description, achieving 100% coverage. The description references the parameter's origin but does not add new semantic information beyond what the schema provides. 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 tool reads the full body and metadata for a rule. It distinguishes from sibling read tools by specifying the context of use after pathrule_get_context, pathrule_goto, or pathrule_get_node. The verb 'Read' is specific and the resource 'Pathrule rule' is unambiguous.

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

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

Explicitly states when to use: after retrieving a rule_id from specific tools. Also implies when not to use by clarifying it does not modify anything, directing agents to update tools for modifications. The guideline is precise and actionable.

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 useful behavioral context: it reads the approved snapshot, returns cloud SKILL.md content, and clarifies it does not install files locally. 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 sentences, no fluff. First sentence states purpose, second provides usage context and constraints. Front-loaded and efficient.

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

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

Tool has one parameter, no output schema. Description explains return content and what it does not do. With annotations, this is fully complete for an agent to use 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 detailed description for skill_id. The tool description does not add extra semantic meaning beyond the schema, so 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?

The description clearly states the tool reads the approved snapshot for one Pathrule skill, using verbs like 'Read' and specifying the resource. It differentiates from siblings by mentioning that pathrule_get_context, pathrule_goto, and pathrule_get_node return a skill_id, and this tool reads the 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?

Explicitly states when to use: 'Use this after pathrule_get_context, pathrule_goto, or pathrule_get_node returns a skill_id.' Also includes a negative guideline: 'it does not install or materialize files locally.' Comprehensive guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds value by disclosing default response behavior (includes file_tree and sampled_contents) and how to compact the response, which is beyond the annotation scope.

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, no wasted words. The key behavior (full vs. partial loading) is stated first, followed by specific parameter guidance. Perfectly concise and 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 the tool's simplicity (non-destructive read, 4 parameters), the description covers the main behavioral choice (full vs. partial) and default fields. However, it lacks details about the return format and the required parameters, leaving some gaps for an agent needing complete guidance.

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

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

Schema coverage is 0%, so the description must compensate. It explains two optional boolean parameters (include_file_tree, include_sampled_contents) and their defaults, but provides no additional meaning for the required parameters (snapshot_id, workspace_id). This partial coverage is adequate but not thorough.

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 it loads a single project snapshot, distinguishing it from sibling tools like pathrule_list_snapshots (for listing) and pathrule_take_snapshot (for creating). The verb 'load' and resource 'project snapshot' are specific and 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 provides guidance on using optional parameters to control response size, but does not explicitly state when to use this tool versus alternatives like pathrule_list_snapshots. The context of a single snapshot vs. listing is implied but not directly contrasted.

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 indicate destructiveHint=true, but the description adds valuable context: that remote MCP may refuse 'applied' status, and that the tool expects refresh_id from prior calls. No contradictions.

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, front-loaded with the main action, followed by the flow and a key constraint. No extraneous 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?

Given the tool has 3 well-described parameters, no output schema, and annotations present, the description covers purpose, flow, and constraints adequately for an agent to use it correctly. Missing return value details, but that is minimal.

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%, but the description adds practical guidance on when to use each status value and where the refresh_id comes from, enhancing the semantic 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 clearly states the tool closes a Pathrule refresh task after reviewing its brief. It uses specific verbs and resources, and distinguishes from siblings by detailing the normal remote flow and when to use rejected vs applied status.

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 provides when to use (after reviewing brief, for rejecting stale signals), when not to use (applied resolutions need local verification via Desktop/CLI), and the intended sequence of calls (list_pending_refreshes, get_refresh_brief, then this tool).

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

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

Describes that the response body is a prompt to follow and outlines the subsequent actions. Although annotations declare readOnlyHint=true, the word 'execute' could be ambiguous; however, the explanation clarifies that execution is done by the agent, so no contradiction. Could be more explicit about the read-only nature.

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

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

The description is a single paragraph covering all key aspects: action, when to call, response handling, and prereqs. It is front-loaded and concise, though could be slightly more structured with bullet points.

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?

Comprehensively covers the setup process, including prerequisites (creating workspace), the response format (a prompt), and post-call actions (scanning, proposing, writing via other tools). No output schema, but description sufficiently explains what to expect.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining default locale and providing guidance on workspace_id: 'Omit only if the user has not picked one yet' and suggesting to create a workspace first.

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

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

The description clearly states 'Fetch the active Pathrule bootstrap brief and execute it,' specifying the verb and resource. It distinguishes from sibling tools like pathrule_get_context, indicating that this tool is for one-time bootstrap, not routine 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?

Provides explicit when-to-use ('Call this ONCE when the user asks to set up / bootstrap / initialize Pathrule') and when-not-to-use ('Do NOT call this mid-task, for already-populated workspaces, or when the user just wants context'), along with alternatives and prerequisites.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which are consistent with the description's claim of recording a snapshot (non-destructive, not read-only). The description adds context that the snapshot persists data for future reasoning, which goes beyond 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 a single paragraph but efficiently conveys key points: the action, the prerequisite AI action, and a list of recommended fields. While it could be more structured (e.g., bullet points), it is front-loaded and every sentence adds 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?

Given 16 parameters, nested objects, no output schema, the description adequately covers the main purpose, required vs recommended fields, and practical constraints (cap at 5000 entries, truncate to ~4KB). It does not discuss error handling or omitted parameters, but overall provides sufficient context 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 56%, so the description adds significant meaning beyond structured schema. It not only lists recommended fields but explains their purpose (e.g., 'sampled_contents for README, package.json / pyproject.toml / Cargo.toml, CLAUDE.md'). This contextualizes parameter usage beyond schema definitions.

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

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

The description clearly states it records a point-in-time inventory of the user's project under a workspace. It distinguishes from siblings like pathrule_read_snapshot and pathrule_list_snapshots by focusing on capture versus read/list. The verb 'take snapshot' is specific and well-defined.

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 AI that it must collect inventory using its own tools before calling this function because 'Remote MCP cannot see the filesystem'. Also provides detailed recommendations on what parameters to include (strongly recommended vs optional), guiding when and how to use the tool.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context: it uses optimistic concurrency via expected_version_id and is cloud-only. No contradictions 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 succinct sentences with the core purpose in the first sentence and key behavioral notes in the second. No redundant words, effectively 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 the tool's complexity (8 parameters, 3 required) and the presence of full schema descriptions and annotations, the description adequately covers key aspects (update, move, concurrency, cloud-only). It does not specify return value, but that is acceptable for a mutation tool.

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

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

The input schema has 100% description coverage, so the description adds limited extra meaning. It notes 'optionally moving it' and 'uses optimistic concurrency', which aligns with the schema but provides little new insight.

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 (update), the resource (memory), and specific elements (content, title, optionally moving). It distinguishes this tool from sibling tools like pathrule_delete_memory, pathrule_read_memory, and pathrule_write_memory by being the update 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 mentions optimistic concurrency and cloud-only, but does not provide explicit guidance on when to use this tool versus alternatives like pathrule_write_memory. It lacks a clear 'when not to use' statement.

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 indicate destructiveHint=true. The description adds value by mentioning optimistic concurrency and cloud-only, which are not covered by annotations. However, it does not disclose auth requirements or what exactly gets destroyed.

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

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

The description is extremely concise at two sentences, front-loading the main action and key behavioral traits. No unnecessary words.

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

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

No output schema is provided, and the description does not explain return values, success/failure behavior, or error conditions. For a tool with complex parameters and a nested object, more context is needed for an agent to fully understand the tool's effects.

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 high (83%), so the baseline is 3. The description adds context for expected_version_id (optimistic concurrency) and the overall purpose of patch and move_to_path, but does not elaborate beyond what the schema already provides.

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

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

The description clearly states it updates a rule's fields and/or path, distinguishing it from other update tools that target memories or skills. However, it does not explicitly differentiate from sibling update tools beyond naming the resource.

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 mentions optimistic concurrency via expected_version_id and cloud-only, but lacks guidance on when to use this tool versus other rule-related tools (e.g., delete, read) or when not to use it. No exclusions or alternatives are provided.

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

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

Annotations already set destructiveHint: true, but description adds valuable context: writes cloud record, may replace fields, may move skill, may fail on version conflict, and explicitly states what it does not do (install files). 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?

Single paragraph, front-loaded with main purpose. Every sentence earns its place, covering usage, side effects, and constraints without 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?

Given complexity (5 params, nested object, destructive, no output schema), description fully covers prerequisites, side effects, version conflict, and explicitly states what it does not do. Complete for safe 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% with detailed parameter descriptions. Description goes beyond by explaining partial update behavior, move functionality, and prerequisites like skill_id. Adds meaningful context over 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?

Clearly states 'Partially update an existing Pathrule skill record' with specific resources and actions. Distinguishes from siblings pathrule_write_skill, pathrule_read_skill, and pathrule_delete_skill by naming them and contrasting use cases.

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 when to use ('only when you already have a skill_id') and when not (for creation, inspection, deletion). Names alternatives and specifies requirements (authenticated connector token, workspace subscription).

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 (which are minimal: readOnlyHint=false, destructiveHint=false), the description adds valuable behavioral details: auto-creation of missing nodes, duplicate blocking, and cloud-only scope (no local filesystem writes). These are important for the agent to understand side effects and constraints.

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 sentences long, each serving a purpose: defining the action, adding constraints, and noting alternatives. It is front-loaded and concise with no unnecessary 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?

Given the tool has 7 parameters and no output schema, the description covers creation behavior and key constraints but lacks information about the return value, error conditions (e.g., invalid workspace_id), and parameter relationships. It is adequate but not fully comprehensive.

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 43% (3 of 7 parameters have descriptions). The description mentions 'allow_duplicate' by name and implies node_path behavior via 'missing nodes auto-create', but does not explain parameter formats, defaults, or constraints beyond what is in the schema. For low coverage (<50%), the description should compensate, but it does not sufficiently.

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 ('create a new memory') and the resource ('at a workspace path'), with specific behavior details like auto-creation of missing nodes and duplicate blocking. It distinguishes from siblings like pathrule_read_memory and pathrule_update_memory by focusing on creation.

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 for when to use the tool: creating a new memory. It explains duplicate blocking behavior and the cloud-only scope, but does not explicitly list alternative sibling tools for reading or updating memories. The mention of installing Pathrule Desktop/CLI for local sync gives an alternative use case.

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 key side-effects: auto-creation of missing nodes and automatic rendering into user configuration files. Annotations are minimal (only flags), so the description carries the burden well, and there is 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?

Three concise sentences: purpose, guidance, and additional behavior. No wasted words. The structure is front-loaded with the core action.

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 complexity (7 parameters, 2 enums, no output schema), the description covers the essential semantics and side-effects. It could mention the return value or confirmation, but the schema descriptions on parameters are already comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the honesty requirement for priority and scope_type, which goes beyond the schema's enum descriptions. It also hints at how node_path relates to auto-creation.

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 'Create a new rule at a workspace path', providing a specific verb and resource. It distinguishes from siblings like pathrule_update_rule and pathrule_write_memory by focusing on rule creation with auto-creation of missing nodes.

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 guidance on using scope_type and priority honestly, especially warning against using high priority unnecessarily. It also notes the cloud-only restriction and the automatic rendering to CLAUDE.md/AGENTS.md. However, it does not explicitly contrast when to use this tool over the similar update_rule tool.

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

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

Annotations only provide flags (readOnlyHint=false, etc.). The description adds critical behavioral info: the tool is cloud-only and does not materialize skills locally. This goes beyond annotations. However, it could mention if the operation is synchronous or async.

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

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

Three sentences, front-loaded with the core purpose, followed by specifics and a caveat. Every sentence adds value without 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?

The description covers purpose, content specification, a special case, and a critical operational limitation. Missing output information, but no output schema exists. For a write tool with 8 parameters, it is fairly complete.

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

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

Schema description coverage is 100%, so each parameter is documented in the schema. The description's mention of 'Content is the full SKILL.md body' and 'For github_ref skills...' largely replicates schema info. 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 verb 'Create' and the resource 'a new skill at a workspace path'. It distinguishes from siblings like update_skill and delete_skill by specifying the action and the content format (SKILL.md body).

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 explicit guidance for github_ref skills (set source and github_url) and warns about cloud-only behavior requiring Pathrule Desktop/CLI for on-disk materialization. It lacks an explicit 'when not to use' but the context is clear enough.

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