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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful context beyond the obvious 'commit' action: it uses the agent's own git identity, and it disclaims staging and pushing. This is useful for an agent deciding whether commit is the terminal step in a workflow, though it does not mention failure modes or return values.

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

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

The description is two short sentences with no filler. The main action and prerequisite are front-loaded, and the exclusions are stated compactly in the second sentence. Every sentence earns its place.

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

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

For a simple two-parameter tool with no output schema and no annotations, the description covers the essential context: what is committed, the prerequisite, identity behavior, and explicit non-behaviors. It does not describe success or error responses, but that is not needed to select or invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both cwd and message. The description itself adds no parameter-level detail beyond what is already in the schema, such as the conventional commit message format. This meets the baseline for a fully schema-documented tool but does not exceed it.

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

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

The description uses a specific verb ('Commit'), names the precise resource ('already-staged files'), and adds a distinguishing detail ('with your own git identity'). This clearly differentiates the tool from siblings like init and the note tools, leaving no ambiguity about what operation is performed.

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 establishes the prerequisite clearly: files must already be staged. It also explicitly states what the tool does NOT do ('Does NOT stage and does NOT push'), which prevents an agent from expecting a full commit-and-push flow. It stops short of naming a specific alternative tool for staging or pushing, but the context is still clear.

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

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

With no annotations provided, the description carries the responsibility for behavioral disclosure. It makes clear that the operation is a read of the active note, which is useful, but it does not describe edge-case behavior such as what happens if no note is open or what exact form the returned content takes.

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, efficient sentence with no filler words. The action and target are front-loaded, giving maximum clarity in minimal space.

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 zero-parameter read tool, this description covers the essential operation and target selection. The only missing context is edge-case behavior like having no active note, which is a minor gap given the simplicity of 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?

The input schema is empty and has 100% coverage, so it provides no parameter meanings. With zero parameters, the baseline is 4, and the description appropriately adds the key semantic: the target note is selected by its currently-open state.

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 exact resource: the note currently open in Obsidian. This clearly differentiates the tool from siblings like get_note and list_notes because it targets the active note rather than a specified path or a collection.

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 'currently open' implies the tool should be used when the agent wants the note that is active in Obsidian, not a note selected by name or path. However, it does not explicitly state when to use this instead of get_note or how to handle cases where no note is open, leaving usage to inference.

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

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

No annotations are provided, so the description carries the full burden. It states the operation is a read ('Read a note'), implying non-destructive behavior. However, it does not disclose behavior on missing notes, invalid paths, or return format. For a simple read operation, this is adequate but not rich; it adds only the 'read' trait beyond the tool name.

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

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

A single, front-loaded sentence with zero waste. The core action ('Read a note') comes first, followed by the method and a helpful example. Every word earns its place; there is no redundancy or fluff.

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

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

The tool is simple: one parameter, no output schema, no annotations. The description provides the essential input format and a clear action. It doesn't mention return value structure or error behavior, but for a basic read operation this is a minor gap. The example and clarity make it sufficiently complete for an agent to call 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 coverage is 100%, so the parameter is already documented. The description adds a concrete example ('Dev days/foo.md') that illustrates the folder structure and file extension, which the schema description ('vault-relative path') lacks. This extra context helps the agent format the path correctly, exceeding the baseline of 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 states a specific verb ('Read') and resource ('a note from the vault') and provides the method (by vault-relative path). This clearly distinguishes it from siblings like list_notes (list all), update_note (modify), and search (query by criteria). The example path format adds precision.

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 use case clear: retrieve a single note when its vault-relative path is known. It doesn't explicitly list alternatives or exclusions (e.g., 'use search if you don't know the path'), but the context is unambiguous. The example path clarifies the expected input format, aiding correct usage.

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

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

With no annotations, the description carries the full burden. It discloses the read source and the scoped write ('inside a managed block'), which is meaningful, but it does not clarify idempotency, whether CLAUDE.md is created if missing, potential overwrite of existing managed content, or error behavior.

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

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

A single sentence that front-loads the action and target, with no wasted words. The managed-block qualifier earns its place by clarifying the write scope.

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

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

For a tool with one optional parameter, no output schema, and no annotations, the description is close to sufficient for correct invocation: it states the source, target, and scoping. Minor gaps remain around idempotency and what happens if the roles note or CLAUDE.md does not exist, but these are not blocking.

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% (cwd is documented as 'project path; defaults to the server's working directory'), so the schema carries the parameter burden. The description adds minimal extra meaning, only tying cwd to 'the project' implicitly. Baseline 3 applies.

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

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

The description names a specific verb+resource: read a fixed roles note and write it into the project's CLAUDE.md within a managed block. This clearly distinguishes it from sibling note CRUD tools (get_note, update_note, patch_note) and search/commit, which operate on different targets or purposes.

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

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

Usage context is implied by the name and description (initializing roles into CLAUDE.md) but not explicitly stated. It does not name alternatives or say when not to use it, though the sibling list makes the boundary reasonably clear.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clarifies that it lists both files and folders, and that an empty folder parameter means root. It doesn't disclose return format, sorting, or whether it includes hidden files, but for a simple read-only listing tool this is a reasonable baseline.

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

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

One sentence, front-loaded with the main action, and the parenthetical example earns its place. 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?

For a simple list tool with one optional parameter and no output schema, the description is mostly complete. It could mention whether the result includes nested items or just immediate children, and whether folders are returned with a trailing slash, but these are minor gaps for an agent deciding whether 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 is 100%, so the schema already documents the 'folder' parameter as a vault-relative path. The description adds the example 'Dev days/' and clarifies that empty means root, which is helpful but not a major addition beyond the schema.

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

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

The description states a clear verb ('List') and resource ('files/folders in the vault'), and adds the optional folder-scoping behavior. It distinguishes itself from siblings like get_note and search by focusing on listing files/folders rather than retrieving content or searching, though it doesn't explicitly name a sibling alternative.

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

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

The description implies when to use it: to list vault contents or a folder's contents. It gives an example path ('Dev days/') which helps. However, it doesn't explicitly state when not to use it or mention alternatives like search for finding notes by content, so usage guidance is adequate but not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation ('insert') but does not disclose what happens if the heading or note does not exist, whether the insertion is destructive, or what side effects occur. For a mutating tool, this is a meaningful transparency gap.

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

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

The description is a single sentence with zero filler, and the core action and target are front-loaded. It is appropriately sized for a tool whose parameters are documented in the schema.

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

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

For a mutating tool with no annotations and no output schema, the description is incomplete. It does not explain the distinction from update_note, the expected return value, or failure behavior when the heading is missing. Schema coverage helps, but an agent cannot fully understand the tool's behavior and selection context from this definition alone.

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

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

The tool description adds no parameter-level meaning; the schema already covers path, content, and heading with 75% coverage. The one undocumented parameter, operation, is reasonably self-explanatory via its enum values (append/prepend/replace), so the baseline score 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 uses a specific verb ('Insert') and names a specific resource ('content relative to an existing heading in a note'), which clearly distinguishes it from read-only siblings like get_note and search. However, it does not explicitly differentiate it from update_note, which is the most likely sibling to confuse it with.

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

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

The intended use is implied: insert content under an existing heading. But there is no explicit guidance about when to prefer patch_note over update_note, nor any exclusions or conditions such as 'heading must already exist.' The core use case is inferable, but alternatives are not addressed.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'plain-text search', which hints at input format but does not reveal return behavior, side effects, access requirements, or whether it is read-only. The agent has no information about what happens on a match or no match, pagination, or performance characteristics.

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 fluff or redundancy. It is concise, but its brevity borders on under-specification, lacking behavioral details that would help an agent. It is well-structured but could have conveyed more context in the same length.

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

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

Given the tool's simplicity—one parameter, no output schema, no annotations—the description is incomplete. It does not clarify the return format, whether results are note names, paths, or content snippets, nor does it specify limits, case sensitivity, or wildcard support. An agent cannot fully anticipate the tool's behavior from this description.

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 fully describes the single parameter 'query' as 'text to search for', and schema description coverage is 100%. The description adds minimal extra semantics—'plain-text' implies no rich query syntax, but this is a weak hint and not a substantive addition over the schema. As the schema covers the parameter, the baseline of 3 is appropriate.

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

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

The description states a clear verb ('search') and a specific resource ('the vault'), making the tool's purpose immediately obvious. It also differentiates from siblings like get_note and list_notes, which suggest retrieval of specific notes or lists, whereas search implies querying across content.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_note or list_notes. It does not mention any prerequisites, filter conditions, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the operation is a PUT that can both create (if absent) and fully overwrite (if present) a note. However, it omits other behavioral details an agent might need, such as whether the write is atomic, whether a commit is required afterward (given a 'commit' sibling exists), or what happens to dependent links.

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 15-word sentence that front-loads the verb and resource, then packs the key semantic (PUT, full overwrite) into the parenthetical. Zero wasted words and the most decision-relevant detail is placed early.

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 two-parameter write tool with no output schema and no nested objects, the description captures the essential behavior: create-or-overwrite with full markdown content via PUT. It is complete enough for correct invocation, with only minor omissions around post-write workflow (commit) and atomicity.

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 both path and content are already documented in the schema. The description adds only marginal value by noting content is 'markdown,' which slightly supplements the schema. Per the baseline rule for high coverage, a 3 is appropriate.

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

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

States a specific verb ('create or overwrite'), a clear resource ('note'), and the HTTP method (PUT). The 'overwrite' phrasing and PUT method clearly signal full-replacement semantics, which distinguishes it from the sibling patch_note (partial update) without needing to inspect either 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 description implies usage context: 'Create or overwrite' plus '(PUT)' tells an agent this is for full-content replacement rather than partial edits. However, it never explicitly names the alternative (patch_note) or states when-not to use it, leaving the routing decision to inference.

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