patch_note

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses key non-destructive behaviors: frontmatter is never touched, and it supports a compare-and-swap guard (prevHash) that fails with hash_conflict. However, it doesn't state whether operations are reversible, whether replace destroys the previous content permanently, or behavior details on failed creation. It provides meaningful safety-relevant context but not exhaustive behavioral disclosure.

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

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

The description is compact and front-loaded with the core purpose in the first sentence, followed by operation definitions and the frontmatter guarantee. It is efficient but could be slightly tighter — the operation list partially duplicates enum values already in the schema, which is minor 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?

With 6 parameters, nested target objects, an optional compare-and-swap guard, and no output schema, the description covers the operation semantics well. It explains createIfMissing nuances, target constraints, and the hash conflict behavior. It could elaborate on return/failure modes beyond hash_conflict (e.g., what happens if target is missing and createIfMissing=false), but overall it's reasonably complete for a surgical editor.

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 structured docs already cover all 6 parameters. The description adds value by clarifying the createIfMissing behavior (appends level-2 heading), the target format nuances (omit ^ prefix / exactly one of heading or block), and the semantic distinction of each operation. This modestly exceeds the baseline 3 by adding operational context not in schema.

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

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

The description opens with a specific verb+resource ('Surgically edit a section of a note') and clearly states targeting mechanisms (heading or block reference). It distinguishes from siblings like append_note, replace_in_note, and patch_frontmatter by emphasizing targeted section editing without rewriting the whole file and never touching frontmatter.

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

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

The description implies when to use this tool (targeted section edits) and explicitly contrasts with whole-file rewriting. However, it does not explicitly name alternative sibling tools (like append_note or replace_in_note) for when a full rewrite or simpler operation is better, so it lacks explicit exclusions/alternatives.

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