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

The description discloses key behavioral traits beyond annotations: it's cloud-only, writes via JWT with RLS enforcement, and lists operations it does NOT perform. This complements the annotations (readOnlyHint=false, destructiveHint=false) by providing context about 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 concise and front-loaded with the main purpose. Each sentence adds necessary context (scoping, exclusions, next steps). While slightly longer than a single sentence, it avoids verbosity and remains focused.

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 (4 parameters, no output schema, good annotations), the description is complete. It explains the creation scope, what is not done, and provides a follow-up call. No additional information is needed for proper 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?

Schema coverage is 100%, so baseline is 3. The description adds high-level context (cloud-only, JWT) but does not elaborate on individual parameters beyond what the schema already provides. Thus, it meets the baseline without significant added 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 clearly states the action ('Create') and the resource ('a new Pathrule workspace inside an organization'). It distinguishes from sibling tools like pathrule_delete_workspace or pathrule_list_workspaces by focusing solely 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 explicitly explains when to use this tool (to create a workspace) and what not to expect (no local folder attachment, no AI client config, no companion files). It also provides a direct next step: 'call pathrule_setup with the returned workspace_id to fetch the bootstrap brief.' This clearly guides the agent's workflow.

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 useful behavioral context: 'No cwd or local_root_path is used' and explains the cta line behavior. 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?

The description is two sentences: the first clearly states the purpose and components returned, and the second provides usage guidance and a behavioral note. No fluff, all sentences earn their place.

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

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

Given there is no output schema, the description adequately explains what the tool returns (memories, rules, skills, etc.) and how to handle the cta line. It covers the prerequisite and the use of workspace_id. However, it does not detail error conditions or the response structure beyond the listed components.

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 does not add significant meaning beyond what the schema provides for each parameter. It reiterates that workspace_id is required and node_path defaults to '/', but that 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, etc.). It sets it apart from siblings by noting that no cwd or local_root_path is used, and the tool returns a broad context unlike specific read 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 tells when to use the tool (to get context for a workspace path) and gives a prerequisite: call pathrule_list_workspaces first if unsure of workspace_id. It also hints at how to handle the cta line in the response. However, it does not explicitly compare to other similar sibling tools like pathrule_get_node or pathrule_get_tree.

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 descriptive burdens are low. The description adds behavioral context: the response splits by audience (CLI vs Desktop) and explains the token-savings angle, which is not covered by 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 long sentence that covers many points. While informative, it could be more concise by splitting into shorter sentences and removing redundant phrasing. It is not optimally structured for quick scanning.

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 no parameters, no output schema, and clear annotations, the description provides a complete picture: what the tool does, when to call it, and how the response should be structured. It covers all necessary context.

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

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

The tool has zero parameters with 100% schema coverage. The description does not need to add parameter details; with no parameters, baseline is 4. The description does not add parameter info, but it is sufficient.

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: 'Explain what Pathrule CLI and Pathrule Desktop unlock beyond Remote MCP.' It specifies the action (explain) and the resource (Pathrule CLI/Desktop capabilities), effectively distinguishing it from sibling tools which are mostly CRUD or action-oriented.

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

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

Explicit usage scenarios are provided: call when user asks 'is there a better way?', 'why do I need to install something?', wants hook-level automation, or wants to compare surfaces. This clearly defines when to use this tool over 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 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 provide readOnlyHint=true and destructiveHint=false. The description adds value by noting that it 'never exposes local filesystem paths' and that the response includes a 'local_runtime.cta' reminder. This provides additional behavioral 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?

The description is two sentences, each concise and informative with no wasted words. Front-loaded with the core purpose, then adds key behavioral 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 no output schema, the description adequately describes what the tool returns (workspace ids) and the reminder. It covers the essential context for a simple list operation, though additional format details could be helpful.

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, and schema description coverage is 100%. Per guidelines, 0 parameters yields a baseline of 4. The description clearly indicates the tool takes no input, so no parameter semantics are needed.

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

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

Description clearly states 'List Pathrule workspaces visible to the authenticated user', specifying the verb (list), resource (workspaces), and scope (visible through cloud RLS). It distinguishes from siblings that create, delete, or read individual workspaces.

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?

Description implies use case: for remote tools, and explicitly says it never exposes local filesystem paths, suggesting alternatives for local work. It provides a concrete reminder about Pathrule Desktop/CLI when doing local code work, which guides the agent on when to mention 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 show readOnlyHint=false (write operation) and destructiveHint=false, which are consistent with logging. The description adds behavioral context by mentioning the stamp requirement for remote MCP, beyond what annotations convey.

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

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

Two concise sentences: first defines purpose, second adds a critical constraint. No redundant or vague language.

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 tool has 9 parameters including nested objects. The description is too brief to fully inform the agent about return values, side effects, or expected behavior beyond the stamp requirement.

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%, so the description must compensate but only mentions workspace_id's role. Other parameters (e.g., domain, action, task_summary) lack any semantic explanation, leaving the agent to infer from enums and names.

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

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

The description clearly identifies the tool as logging a file-modifying response from a remote MCP client, which is a specific verb+resource. It differentiates from sibling CRUD tools by being the only logging 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 states a requirement for remote MCP to include workspace_id and stamps ai_client='cloud-connector', giving partial usage context. However, it does not specify when not to use it or provide 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, so the description adds context about when Remote MCP may refuse status='applied'. It does not detail side effects beyond 'close', but the combination is adequate.

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, no fluff. First sentence defines purpose, second provides workflow, third warns about limitations. Each 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 description covers the workflow, parameter usage, and key constraints. However, it does not describe the response format or success/error handling, though the tool is simple enough that this is a minor gap.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning by explaining the appropriate use of each status value and the purpose of the note parameter, especially for rejecting stale refreshes, and ties refresh_id to sibling tool outputs.

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 refresh task') and resource, and differentiates from sibling tools like pathrule_list_pending_refreshes and pathrule_get_refresh_brief by specifying it as the concluding step in a normal remote flow.

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 the recommended workflow: list pending refreshes, get brief, then use this tool with status='rejected'. Also warns against using status='applied' via Remote MCP and directs to Pathrule Desktop/CLI for such cases.

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 annotations, the description discloses that missing nodes auto-create, duplicate titles are blocked unless allow_duplicate is set, and writes are cloud-only. These are important behavioral traits not captured in the annotations (readOnlyHint=false, destructiveHint=false).

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

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

Three sentences with no wasted words. Each sentence conveys essential information: purpose, key behaviors, and cloud-only nature. The most important info 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 the complexity (7 parameters, no output schema) and annotations, the description covers the key behavioral aspects. It does not describe return values or error conditions, but the agent can infer success from the create operation. It is sufficiently complete for selection and 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 low (43%). The description adds meaning for allow_duplicate (blocking duplicates) and node_path (auto-creation), but does not explain title, content, or source parameters beyond what the schema provides. It partially compensates for the low 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 starts with a clear verb+resource: 'Create a new memory at a workspace path.' It adds specific behaviors like auto-creation of missing nodes and duplicate blocking, which distinguishes it from sibling tools like pathrule_read_memory or pathrule_update_memory.

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 the tool is cloud-only and never writes to the local filesystem, and suggests an alternative (Desktop/CLI) for on-disk sync. It provides clear context for when to use this tool, though it does not explicitly list cases where another tool would be better.

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 sparse (no destructiveHint, etc.), but the description discloses key behaviors: auto-creation of nodes, cloud-only operation, and automatic rendering into user files. This adds value beyond the minimal annotation set.

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

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

Two sentences with front-loaded purpose and efficient use of words. Every sentence adds distinct value: core action and then behavioral/usage 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 7 parameters (6 required) and no output schema, the description covers key behavioral traits and usage notes. It is complete enough for correct tool invocation, though could mention typical response structure.

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 description adds only marginal value by reiterating guidance on scope_type and priority. 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 'Create a new rule at a workspace path' with a specific verb and resource. It also mentions auto-creation of missing nodes, differentiating from update or read siblings.

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

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

Provides guidance on using scope_type and priority honestly, specifying when 'high' is appropriate. Also notes cloud-only behavior and automatic rendering, but does not explicitly exclude alternatives or 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 minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds substantial behavioral context beyond annotations: it explains the tool is cloud-only, does not materialize to disk, and describes the content format (full SKILL.md body including frontmatter and markdown). It also clarifies the use of github_ref source with github_url. 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?

The description is concise with three sentences, each adding distinct value. It front-loads the primary action and immediately follows with critical usage details. There is no redundancy or unnecessary 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 8 parameters (5 required) and no output schema, the description covers the key behavioral aspects: cloud-only nature, materialization requirement, content format, and source attribute usage. It does not elaborate on return values, which is acceptable since no output schema is provided. The description is sufficient for an agent to understand when and how to use the 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%, setting baseline at 3. The description adds value beyond the schema by explaining the content parameter's format ('Full SKILL.md body including frontmatter and markdown'), the node_path example ('/ or /packages/app'), and the name convention ('usually kebab-case'). It also clarifies the relationship between source and github_url.

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 skill at a workspace path.' This specifies the action (create) and the resource (skill at a workspace path). It differentiates from sibling tools like pathrule_read_skill and pathrule_delete_skill by describing the specific creation process and its cloud-only nature.

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 when to use this tool (cloud creation) and explicitly states its limitation: 'Cloud-only: does NOT materialize the skill into .codex/skills, .claude/skills, .cursor/skills, etc. — Pathrule Desktop or CLI is required for on-disk skill materialization.' While it does not name alternative tools, the context of sibling tools implies other options like pathrule_update_skill for modifications.

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