Pathrule

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds a genuine behavioral precondition not present in the schema: expectedVersion must equal the memory's current revision, implying an optimistic-concurrency failure mode on stale versions. It still omits what happens on version mismatch and any permission requirements.

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

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

A single sentence with the action and the concurrency precondition front-loaded, and no filler. Every clause carries information the caller needs.

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

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

For a destructive operation the description covers the essentials (target and version guard) and annotations carry reversibility, but with 6 parameters at 50% coverage and no output schema, the role of path, workspace_id, and the idempotency/retry parameters is left entirely to the 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 coverage is 50%. The description explains the two required parameters (id as the target, expectedVersion as the current revision), but adds nothing for path, workspace_id, operation_id, or idempotency_key, and path has no schema description at all despite being a listed property on a delete-by-id tool.

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

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

States a specific verb (Delete), resource (a memory), and keying method (by id) within the connected Pathrule workspace, which cleanly separates it from pathrule_delete_rule and pathrule_delete_skill. An agent can identify the tool's job without opening the schema.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are named despite an obvious sibling set (delete_rule, delete_skill, update_memory). The agent must infer that this is the deletion path for memories and that update_memory is the non-destructive alternative.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, openWorld=false, so the safety profile is covered; the description adds real behavioral value by disclosing the optimistic-concurrency precondition ('expectedVersion must be its current revision'). It still omits what happens on a version mismatch and does not address the retry/idempotency surface the schema exposes.

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

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

A single tight sentence with the action and its key precondition front-loaded; no filler, no restatement of the tool name.

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 and the concurrency precondition for a mutation tool with no output schema and an already-complete annotation safety profile. Gaps remain around failure behavior on version conflict, the undocumented path parameter, and the idempotency/operation_id retry surface.

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

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

Schema coverage is only 50%, so the description must compensate, and it explains expectedVersion (current revision) — a parameter with no schema description. However, it leaves id and path undocumented, so compensation is only partial.

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

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

States a specific verb+resource ('Delete a rule by id') and disambiguates the resource against sibling deleters (delete_memory, delete_skill). It also names the target workspace, but does not explicitly point the agent at alternatives for other 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?

There is no when-to-use/when-not guidance and no reference to sibling tools such as pathrule_update_rule or the read/list variants. The single clause about expectedVersion is an invocation constraint, not selection guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so safety is covered structurally. The description adds genuinely useful context by stating expectedVersion must be the current revision, revealing an optimistic-concurrency precondition, but it never says whether the delete is hard or soft, or how a version conflict surfaces.

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

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

A single tight sentence with the action and its key precondition front-loaded; nothing is redundant.

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

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

For a destructive, non-idempotent mutation with no output schema and six parameters, the description covers the versioning rule but omits conflict/error behavior and path semantics, leaving an agent slightly under-informed.

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 50%, and the description usefully explains the most consequential parameter, expectedVersion (current revision), which the schema leaves bare. However id, path, and the idempotency/operation distinction get no added meaning, leaving part of the gap unaddressed.

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

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

States a specific verb (Delete) plus resource (a skill by id) and names the workspace scope. Siblings like pathrule_delete_memory and pathrule_delete_rule make the resource distinction evident, though the description itself doesn't explicitly contrast them.

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

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

Usage is implied by the destructive verb and the naming convention, but there is no explicit guidance on when to delete versus calling pathrule_update_skill or pathrule_history_skill, nor any stated 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 already declare readOnly, idempotent, non-destructive, non-openWorld, and the description correctly echoes 'Read-only'. It adds genuinely useful behavior beyond annotations: the caps (at most 20 per kind and 1 MiB), that parent folders are included, and that the remainder of the workspace comes back only as a title index.

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

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

One dense sentence, front-loaded with the verb and resources, then scope, then limits, then a safety tag. No filler, though the parenthetical limits make it slightly crowded.

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

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

With no output schema, the description usefully characterizes the return payload (full text plus a title index of the rest). Truncation/pagination behavior beyond the stated caps and what the title index allows are not elaborated, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 50%: workspace_id is documented in-schema, but path has no schema description. The description supplies the key missing semantics for path ('workspace-relative path and its parent folders'), which is real added value, but the default '/' behavior and the 2048 max length are left to the schema alone.

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

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

States a concrete verb (read) plus the three resource kinds (memories, rules, skills) and the scoping rule (workspace-relative path and its parent folders). It is clear what the tool returns, though it does not name a sibling to distinguish against — the differentiation from pathrule_read_* and pathrule_list_* is left implicit.

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

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

The description implies usage by describing the aggregate, path-hierarchical scope, but never states when to choose this over pathrule_list_memories or pathrule_read_rule. The agent must infer that this is the 'get everything relevant to a path' entry point.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Read-only' merely restates the structured data. Nothing is added about pagination, ordering, or how the workspace binding constrains results.

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

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

A single front-loaded sentence plus a two-word safety note; there is no filler. It is appropriately sized for what it actually conveys, even if it conveys too little.

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

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

With 4 parameters, 25% schema coverage, an opaque 'before' parameter, and no output schema, the definition leaves real gaps. An agent cannot tell how to page through revisions or what 'before' does without guessing.

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 25% (only workspace_id is documented in the schema). The description explains none of the shadowed parameters: 'path' defaults to '/' but its role for a memory lookup is unexplained, and 'before' (integer, minimum 1) has no stated meaning at all.

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

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

States a specific verb and resource ('List the earlier revisions of a memory') and scopes retrieval by id. It is distinguishable from pathrule_read_memory (current state) and pathrule_history_rule/skill (other resource types), though it never explicitly names those 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?

The phrase 'earlier revisions' implies you use it to inspect history, but there is no explicit when-to-use vs. pathrule_read_memory guidance, no prerequisites, and no statement about what happens if the id has no history.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so 'Read-only' merely restates structured data. Nothing is added about ordering, truncation, pagination, or how many revisions come back — the details an agent actually needs for a history call.

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

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

Two short sentences, front-loaded with the operation and resource. The trailing 'Read-only' clause is redundant with annotations and slightly wasteful, but overall there is no bloat.

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

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

No output schema exists, so the description carries the burden of describing what a revision record looks like — it says nothing. Combined with an undocumented 'before' parameter and no guidance on ordering or result limits, an agent cannot confidently invoke this beyond the required id.

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 25% (just workspace_id), and the description covers only the required 'id' implicitly via 'found by id'. The 'path' (defaulting to '/') and especially 'before' are undocumented in both schema and description, so 'before' semantics — presumably a revision bound — must be guessed.

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

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

States a specific verb ('List') and resource ('earlier revisions of a rule') plus the lookup key ('found by id'), which separates it from pathrule_read_rule (current version) and the parallel history_memory/history_skill tools. It does not name those siblings explicitly, but the resource qualifier does the differentiating work.

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

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

Usage is only implied: an agent can infer 'use this when you need prior versions of a rule.' There is no explicit when-to-use, no precondition, and no pointer to pathrule_read_rule as the current-state alternative or to the memory/skill history variants.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's 'Read-only' merely restates structured data. It does add the notion that results are 'earlier revisions' rather than the current version, but says nothing about ordering, pagination, or result limits.

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

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

Two short, front-loaded sentences with no filler; the verb and resource lead. The trailing 'Read-only' duplicates the annotations and is the only mildly wasted clause.

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 4-parameter tool with no output schema and 25% schema coverage, the description is too thin. It omits what a revision record contains, whether results are paginated, how 'before' scopes the window, and what 'path' means for a skill.

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 25% (just workspace_id), so the description must compensate but does not. It covers the required 'id' but leaves 'path' (default '/', maxLength 2048) and 'before' (integer >= 1) completely unexplained in both schema and 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?

States a specific verb and resource ('List the earlier revisions of a skill') plus the lookup key ('found by id'). The 'skill' resource clearly separates it from the sibling pathrule_history_memory and pathrule_history_rule, though it never names those alternatives explicitly.

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

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

There is no when-to-use or when-not-to-use guidance. An agent must infer that this is for revision history rather than current state, and that pathrule_read_skill or pathrule_list_skills are the alternatives for reading the live skill.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description reinforces 'Read-only.' The description adds genuinely new behavioral detail not in annotations: the 100-item page cap and newest-first ordering, which directly affect how the agent iterates. It omits error/permission behavior, so not a 5.

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

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

A single tight sentence that front-loads the core operation and packs scope, ordering, page size, and the read-only guarantee without waste.

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 read-only list tool with no output schema, the description covers ordering, page size, and paging adequately. It stops short of describing the returned memory shape or whether an empty path defaults to root (that only lives in the schema default), so it is strong but not fully self-contained.

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

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

Schema coverage is 67% and the two documented params (offset, workspace_id) are handled by the schema. The description adds meaning for the path parameter (workspace-relative, memories 'saved under' it) and reinforces the offset/paging contract, going beyond the bare schema for the undocumented path field.

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

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

States a specific verb (list) and resource (memories) scoped to a workspace-relative path within the connected Pathrule workspace. The scope and ordering (newest first) clearly distinguish it from siblings like pathrule_read_memory and pathrule_history_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?

Gives concrete usage context: 'at most 100 per call; pass offset for the next page,' which tells the agent how to page. However, it never names an alternative or an exclusion condition relative to read_memory/history_memory, so the when-to-use guidance is implied rather than explicit.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' is largely redundant. The description does add genuinely new behavior: result ordering (newest first) and the 100-item page cap, which an agent needs to page correctly.

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

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

A single dense sentence with the scope, ordering, page cap, paging instruction and safety profile front-loaded in that order. No filler and nothing repeated.

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

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

For a no-required-param list tool with annotations covering the safety profile, the description covers scope, ordering and pagination adequately. Since no output schema exists, it could say a bit more about what a rule entry looks like, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 67%; the `path` property carries no schema description, and the description compensates by clarifying it is a workspace-relative path. The offset/paging semantics are already in the schema, and the description restates the page-size tie-in usefully.

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

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

Specific verb (List) plus resource (rules) scoped to a workspace-relative path, and the word 'rules' inherently distinguishes it from the list_memories/list_skills siblings. It stops short of explicitly naming those alternatives, so an agent must infer the split from the resource noun alone.

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

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

Usage is implied by the scoping (list rules under a path) and it gives a concrete paging recipe ('pass offset for the next page'), but there is no explicit when-to-use/when-not guidance and no mention of the sibling list tools that fetch memories or skills instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavior beyond the schema: a 100-item cap per call, newest-first ordering, and offset-based paging. It does not describe the shape of returned items, which keeps it from a 5.

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

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

A single front-loaded sentence packs the verb, resource, scope, sort order, page size, and paging instruction with zero filler. Nothing wasted, nothing buried.

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

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

With no output schema, the description must carry return behavior, and it usefully documents page size, ordering, and the paging signal (a full page means more may exist). Minor gap: it doesn't hint at the fields a skill entry contains, but for a simple list tool the definition is largely sufficient.

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 67%, with offset and workspace_id documented in-schema but path left bare. The description compensates by defining path as "workspace-relative" and explaining the paging contract ("at most 100 per call; pass offset for the next page"), adding meaning beyond the raw schema.

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

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

States a specific verb and resource ("List the skills") plus scope ("saved under a workspace-relative path in the connected Pathrule workspace") and ordering (newest first). This cleanly distinguishes it from sibling list tools such as pathrule_list_memories and pathrule_list_rules.

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

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

The description makes the tool's context clear (enumerating skills under a path) and notes it is read-only, but never says when to prefer it over alternatives like pathrule_get_context or pathrule_read_skill, nor any exclusions. Usage is implied rather than prescribed.

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 supply the generic mutation/idempotency profile, and the description adds real behavioral detail: over-length task_summary is stored shortened with a warning and never refused (so retries are pointless), files are capped at 60, and the server cannot see the caller's filesystem. It does not explain what the stored entry looks like or rejection conditions beyond summary length, so it stops short of 5.

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

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

Front-loads purpose in the first sentence, then the when-to-call rule, then parameter caveats. Four dense sentences with no filler, though the parameter guidance is packed tightly enough to be slightly hard to scan.

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 an 11-param, nested-object mutation tool with no output schema, the description covers the trigger, the cardinality rule, and the failure/truncation behaviors that matter most for correct invocation. Gaps remain around the taxonomy enums and the optional verbose/operation_id interplay, but the core call path is well covered.

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 55%, and the description compensates for the least self-documenting parameters: task_summary should be one sentence under ~300 chars, and files_touched paths must be workspace-relative. It adds nothing for the enum params (domain/action/scope), which the schema already constrains, leaving some residual gap.

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

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

States a specific verb (log) and resource (a file-modifying response/activity entry) with the payload scope ('structured taxonomy and file paths'). The resource is unique among siblings, which are all memory/rule/skill CRUD tools, so an agent can route to it unambiguously.

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 trigger ('Call this AFTER every response where you created, edited, or deleted files') plus a frequency constraint ('one call per response, not per file') that rules out the obvious misuse. No alternative tool exists for this purpose, so no alternative-routing text is needed.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds one genuinely useful behavioral detail (the full memory text is returned, not a summary), but says nothing about missing-id errors, visibility/permission or how the optional path scopes the lookup.

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

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

Two short, front-loaded sentences with the essential information first ('Read one memory by id, with its full text'). The trailing 'Read-only' largely restates the readOnlyHint annotation, so it is not fully waste-free.

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

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

With no output schema, the description correctly discloses that the full text is returned, and annotations cover safety. However, the role of the optional path parameter and the failure behavior for unknown ids remain unexplained for a tool whose schema is only a third documented.

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 33% (path and id have no schema text), so the description should compensate; it mentions 'by id' but adds nothing about the path parameter or how it interacts with id/workspace_id. Only one of three parameters gains any meaning from the 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?

States a specific verb and resource (read one memory by id) plus the return shape (full text), which separates it from list_memories and from the rule/skill readers. It doesn't explicitly contrast the sibling read tools, but the resource noun is unambiguous.

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

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

The only usage signal is the implicit 'by id', meaning the caller must already have an id; there is no statement of when to use this versus pathrule_list_memories, pathrule_get_context, or pathrule_history_memory. No preconditions or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=false, so 'Read-only' is pure repetition and adds nothing. The phrase 'with its full text' is genuinely additive since there is no output schema, but nothing is said about not-found behavior, error modes, or the workspace-binding constraint beyond what the schema already carries.

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

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

Two short, front-loaded sentences with no wasted words; the primary action leads and the read-only note trails. It is efficient, though the extreme brevity contributes to the missing parameter and usage detail.

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

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

With no output schema, the description does useful work by noting the full rule text is returned. However, the unexplained `path` parameter and absent id-vs-path semantics leave meaningful gaps for a three-parameter tool with a large sibling family.

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 33%: the `id` and `path` parameters carry no descriptions at all. The description says the lookup is 'by id' but never explains the `path` parameter (default '/', max 2048) or how path and id interact, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Read one rule by id') and hints at scope ('with its full text'), which cleanly separates it from siblings like pathrule_list_rules and pathrule_write_rule. It does not name the sibling it displaces, so it falls short of a 5.

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

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

The description gives no explicit when-to-use guidance and never names an alternative. It implicitly assumes the caller already has an id, but says nothing about when to use pathrule_list_rules to discover ids instead, or when pathrule_history_rule would be more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds only 'with its full text' (returns the complete body, not a summary) while 'Read-only' merely restates the annotation. No pagination or size caveats are given.

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

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

Two short fragments, front-loaded with the core action and no filler. It is terse rather than padded, though the trailing 'Read-only' clause earns little given the annotation already says it.

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 with no output schema, the description hints at the return ('full text') but omits anything about the path scoping, workspace binding, or size/truncation behavior. Adequate at minimum viable level, but not complete for a 3-parameter 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 only 33%, and the description explains only the id parameter implicitly. It says nothing about what 'path' (default '/') scopes or how workspace_id binds, so it fails to compensate for the undocumented parameters.

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

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

States a specific verb+resource ('Read one skill by id') and adds scope ('full text'), so it is distinguishable from the read_memory and read_rule siblings by resource noun. It does not explicitly contrast itself with those siblings, but the resource naming carries most of the differentiation.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_skills or history_skill. The agent is left to infer that this is the single-item retrieval path when an id is known.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds valuable context beyond that: the old text is overwritten but earlier revisions remain in history, and expectedVersion enforces optimistic concurrency. It stops short of describing conflict/error behavior, keeping it out of 5 territory.

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, zero filler, with the overwrite semantics and version precondition front-loaded. Every clause carries information an agent needs.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the overwrite/history behavior and the version guard, which are the critical facts. Missing only error-on-conflict behavior and path-change semantics.

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

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

Schema coverage is 50%, and the schema itself documents body, operation_id, workspace_id, and idempotency_key. The description usefully explains the non-obvious expectedVersion precondition, but says nothing about path, whether workspace binding can change, or how title/body map to the update.

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

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

States a specific verb (Replace) and resource (title and text of an existing memory) plus the lookup key (by id). Against siblings like pathrule_write_memory (create) and pathrule_update_rule/update_skill, the resource noun alone differentiates it clearly.

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 usage: replacing an existing memory as opposed to creating one, and it names the precondition (expectedVersion must be its current revision). But it never explicitly says when to choose this over pathrule_write_memory or pathrule_history_memory, or what to do on a version mismatch.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds genuinely useful context beyond them: earlier revisions are preserved in history, and expectedVersion must match the current revision (an optimistic-concurrency contract). It still does not say what error/behavior results from a version mismatch, which is the main remaining gap.

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

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

Two tight sentences with the mutation and its overwrite semantics front-loaded, then the version precondition. No filler.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the essential behavior (full overwrite, history retention, version precondition). It is nearly complete, missing only failure-mode behavior on version conflict and permission requirements.

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 50%; expectedVersion has no schema description, and the description compensates by explaining it must be the current revision. 'id' is clarified as the lookup key and 'body' is implicitly the 'text' being replaced, but path, workspace_id, operation_id and idempotency_key get no added meaning from the description (some are covered by the schema instead).

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

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

States a precise verb and resource ('Replace the title and text of an existing rule, found by id') and clarifies the scope is a full replacement of title+body rather than a partial patch. The resource noun 'rule' separates it from the update_memory/update_skill siblings, and 'found by id' identifies the lookup key.

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

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

Usage is only implied: you need an existing rule id and a current revision. There is no explicit guidance on when to prefer this over pathrule_write_rule (create) or the memory/skill update variants, and no stated prerequisites such as read-before-write or permissions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that the current text is overwritten while 'earlier revisions stay in its history', and that expectedVersion must equal the current revision (optimistic concurrency). It says nothing about idempotency despite the idempotency_key/operation_id params, but that is not a contradiction of idempotentHint=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?

Two dense sentences, front-loaded with the action and lookup key, followed by the overwrite/concurrency constraint. Every clause earns its place; only the mismatch between 'text' and the actual 'body' param is slightly loose.

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 an 8-parameter destructive mutation with no output schema, the description covers the two most important behaviors (overwrite semantics and the version precondition). It omits workspace binding, path scoping, and retry/idempotency behavior that a caller of a destructive tool would benefit from.

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 50%; body, operation_id, workspace_id and idempotency_key carry their own schema descriptions. The description adds meaningful semantics for expectedVersion ('must be its current revision') and id, but leaves path and title undocumented in both schema and description, so it only partially compensates.

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

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

States a specific verb+resource ('Replace the title and text of an existing skill') and the lookup key ('found by id'). This distinguishes it from write_skill (creation), read_skill, delete_skill, and history_skill without opening any schema.

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 word 'existing' implies this is the update path rather than creation, but no sibling is named and no when-to-use/when-not guidance is given. An agent must infer from the sibling list that write_skill is the create alternative and history_skill retrieves revisions.

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

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

Annotations already declare this is a non-destructive, non-idempotent mutation. The description adds useful behavioral scope by saying it 'Adds an item and changes nothing else', clarifying that it is an additive create rather than an update with side effects. It still does not explain duplicate/retry behavior for the non-idempotent write path.

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

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

Two short sentences, front-loaded with the action and scope, and no wasted text. The second sentence immediately clarifies side-effect behavior.

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 six-parameter create tool, the description covers the core action, path scope, and additive side-effect profile, while annotations and schema handle safety and most parameter details. The main remaining gap is that it does not explain what is returned or how the operation_id/idempotency_key parameters relate to retry behavior, but the schema fills part of that gap.

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

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

Schema coverage is 67%, and the description meaningfully compensates for the undocumented path parameter by specifying it is 'workspace-relative'. The remaining parameters, including operation_id and workspace_id, are already described in the schema, so the description adds enough semantic value without repeating them.

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

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

The description uses a specific verb-resource pair: 'Save a new memory', scoped to 'a workspace-relative path' and the connected Pathrule workspace. The word 'new' and the phrase 'Adds an item' distinguish it from update/read/delete siblings without needing to name them.

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

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

It clearly signals the intended case: creating a new memory rather than changing an existing one. It does not explicitly name update_memory as the alternative for existing items, but the 'new' condition gives enough context for correct selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral trait — 'adds an item and changes nothing else,' i.e. it is additive and does not mutate existing rules. It says nothing about the durable-retry/idempotency behavior the schema exposes, which is the notable gap.

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

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

Two short sentences with no filler; the resource and location are front-loaded before the behavioral note. Nothing is redundant, though the second sentence is thin enough that it borders on padding.

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 six-parameter mutation tool with annotations covering safety and no output schema, the description is minimally adequate: it names the resource, the target location, and the additive nature of the write. It omits creation-vs-update routing and any mention of the retry/idempotency parameters, leaving material gaps for an agent deciding how to call it.

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 sits at 67%, so the schema documents most parameters (body, operation_id, idempotency_key, workspace_id). The description adds meaning for the otherwise undocumented 'path' parameter by calling it 'workspace-relative,' but says nothing about the 2048/500 length limits or the default '/' location beyond that phrasing.

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

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

States a concrete verb and resource: 'Save a new rule' at a 'workspace-relative path in the connected Pathrule workspace.' The word 'new' distinguishes it from pathrule_update_rule and the read/delete/history siblings without needing their schemas. It does not, however, draw any explicit line against the parallel write_memory/write_skill 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?

The description never states when to choose this tool over pathrule_update_rule or the write_memory/write_skill alternatives. 'Save a new rule' implies creation, but there is no explicit prerequisite, no when-not-to-use note, and no routing to a sibling for the update or overwrite 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds the useful clarification that this is purely additive ('Adds an item and changes nothing else'), consistent with destructiveHint=false. It does not cover what happens when a skill already exists at the path, auth requirements, or the retry/idempotency behavior that the schema hints at.

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

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

Two short sentences, front-loaded with the action and scope, with no filler. Every clause carries 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 6-parameter write tool with no output schema, the description covers purpose and additive semantics but omits conflict/overwrite behavior at an existing path, error handling, and the idempotency/retry story implied by operation_id and idempotency_key. Adequate but with clear gaps.

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

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

Schema description coverage is 67%, so the schema already documents body, operation_id, workspace_id, and idempotency_key. The description adds only the semantics of the path parameter as 'workspace-relative', and says nothing about title, body, or the idempotency/operation_id relationship. That matches the baseline for mid coverage.

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

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

States a specific verb (Save) and resource (a new skill) plus the scoping constraint that the path is workspace-relative in the connected Pathrule workspace. The resource noun distinguishes it from siblings like pathrule_write_memory and pathrule_write_rule. It does not explicitly contrast with pathrule_update_skill, but 'new' implies 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?

No explicit when-to-use guidance and no named alternatives. The agent must infer that pathrule_update_skill is for existing skills and that this tool only creates new ones; the description never states that or any prerequisite.

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