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

Annotations already disclose readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely valuable non-annotation context: the read-then-conditional-write semantics and the fact that a concurrent edit is reported rather than silently overwritten, which explains why the operation is non-idempotent.

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, zero filler, with the core purpose front-loaded and the concurrency caveat following. Every clause 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 mutation tool with no output schema, the description covers purpose, concurrency behavior, and the conflict outcome, while annotations carry the safety profile. It stops short of explaining how the conflict is 'reported' (error vs. response field) or mentioning the separator, leaving 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?

Schema description coverage is only 33%, so the description must compensate. It clarifies the semantics of the appended 'text' and the implicit target note, but never mentions the 'separator' parameter or its blank-line default, which is the one parameter the schema does document. Partial compensation only.

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+resource ('Append text to the end of a note') and immediately contrasts the approach with the alternative of resending the whole body, which is exactly what sibling update_note would do. An agent can distinguish this from update_note without opening 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 phrase 'without resending its whole body' clearly implies this should be chosen over a full-body update when only appending. However, it never names update_note as the alternative or states exclusions, so the routing guidance is inferable 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 write semantics (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds real value beyond that: category folders are auto-created as a side effect, and the server sanitises title and category, so the agent must reconcile against the response. Auth, rate limits, and error behavior remain undisclosed, keeping it short of 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?

Three short sentences, front-loaded with the action and followed by the two behaviours an agent cannot infer. No filler or restated schema content.

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?

There is no output schema, but the description explicitly warns that the response values (sanitised title/category) supersede the supplied ones, which partially compensates. Missing pieces are minor: no indication of failure modes or of what the created note's identifier looks like.

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 category is documented in-schema), so the description must compensate. It does explain category as a "/"-delimited folder path that is auto-created, but content and favorite receive no semantic clarification in either place.

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 ("Create a note") and immediately clarifies how the category field behaves. It does not explicitly contrast with create-adjacent siblings like append_to_note or update_note, but the purpose itself 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?

Usage is implied by the verb and by the note that category folders are auto-created, but there is no statement of when to prefer this over append_to_note or update_note, and no prerequisites 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description genuinely adds beyond that by disclosing the soft-delete behavior: the file lands in the Nextcloud trash, is recoverable from the Files app, and cannot be restored by this server.

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 destructive action front-loaded followed by the recovery caveat. Every clause earns its place; no 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?

For a delete tool whose annotations already carry the destructive/idempotent profile, the recovery semantics are the key missing context and they are provided. The only gap is the unexplained 'id' parameter, which is a modest omission given there is no output schema to worry about.

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 single 'id' parameter has 0% schema description coverage, leaving the description to compensate — but it says nothing about what 'id' identifies (a note id) or its expected form. With one required, undocumented parameter, the description fails to add the needed meaning.

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 ('Delete a note') matched to the tool name. It is unambiguous against siblings like update_note or append_to_note, though it does not explicitly name any alternative to distinguish itself.

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; the description only explains what happens after the call. It never mentions prerequisites (e.g., note must exist) or any alternative to deleting, such as emptying/ignoring the note.

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, and non-destructive, so safety is covered. The description adds genuine context beyond annotations by explaining the etag's role in optimistic-concurrency writes to update_note, though it says nothing about the exclude parameter's effect on the response.

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, front-loaded with what is fetched and then the etag workflow. Every clause earns its place with no 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?

With no output schema and no schema descriptions, the description should carry more of the load. It names content and etag but omits the other likely return fields and the exclude parameter entirely, leaving a notable gap for a tool whose schema is undocumented.

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 0% for both parameters. The description mentions content (which loosely maps to an exclude enum value) but never explains the required id or, critically, the exclude array that suppresses fields. It leaves the agent without guidance on a parameter the schema does not describe.

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 (Fetch) and resource (one note) plus what is returned (content and etag), which clearly distinguishes it from list_notes and the mutation siblings. No ambiguity about what the tool does.

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 a clear use context: retrieve the etag to make a conditional write via update_note. It does not explicitly address when NOT to use it versus list_notes, but the single-note scope and the write-workflow linkage are strong 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, idempotentHint=true, destructiveHint=false, so safety is structured. The description adds value by listing the exact settings fields, but it discloses no extra behavioral traits such as defaults or what happens if settings are unset. With annotations covering the safety profile, a 3 is appropriate.

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 verb and resource and packs the field list efficiently. No 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 zero-param read tool with rich annotations and no output schema, the description covers purpose and returned fields adequately. It could note why settings matter (e.g., how folder/suffix affect note storage), but nothing needed to call 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?

There are zero parameters, so the baseline is 4. The description's field list actually describes the return shape, which adds meaning given no output schema exists, though it is not parameter semantics per se.

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 (Read) plus resource (Notes app settings), and it enumerates the exact fields returned. An agent can distinguish this read-only tool from its sibling update_settings without opening 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 name and read-only framing imply when to use it versus update_settings, but the description never states an explicit condition or names the alternative. Usage is only implicitly conveyed.

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 safety is covered. The description adds meaningful non-obvious behavior: categories are derived from notes because the API has no category endpoint, and empty categories will not appear even though the Notes app displays them. That is exactly the kind of gotcha an agent needs, though ordering and count semantics are not spelled out.

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 what is listed and what is returned, then the derivation caveat. Every clause carries information, though the second sentence is slightly dense and could be split for readability.

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?

There is no output schema, so the description must convey the return shape — it does, naming direct and recursive note counts. Combined with the missing-empty-categories caveat, an agent can call and interpret this correctly; only result ordering and count definitions remain unstated.

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 takes no parameters, so per the rubric the baseline is 4. The description correctly adds nothing about parameters, and it does clarify what the returned counts mean ('direct and recursive'), which is the closest thing to input/output semantics available here.

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 and resource ('List every category') plus its precise scope ('that contains at least one note') and the data it returns ('direct and recursive note counts'). It does not explicitly name a sibling to contrast with, but the scope note effectively separates it from any notion of listing all categories.

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: call this to enumerate categories with notes. There is no explicit when-to-use guidance, no mention of alternatives (e.g., rename_category for modifying, set_note_category for assignment), and no prerequisites such as authentication. The caveat about missing empty categories is helpful context but not when-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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the lower bar applies. The description adds non-obvious server behavior — exact category matching — and a response-size optimization, which are genuinely beyond the structured fields. Pagination behavior for chunkCursor/chunkSize is still not described.

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 tight sentences, front-loaded with purpose then the two non-obvious gotchas. Every clause carries information an agent would otherwise have to guess.

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 zero-required-param list tool with a fully documented schema and a rich annotation set, this is nearly complete. The remaining gap is that pagination flow (chunkCursor/chunkSize) and pruneBefore semantics are 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 100%, so the baseline is 3, and the description exceeds it by explaining why recursive matters (exact-match category semantics) and what exclude is for (shrinking the response). pruneBefore and the chunk parameters get no added meaning in the text.

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 notes') and immediately narrows scope with 'optionally filtered by category'. It is distinguishable from get_note/list_categories by the plural listing semantics, though it never names a sibling 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?

Gives clear operational guidance: pass recursive=true when you want subcategories because matching is exact, and use exclude=["content"] when only metadata is needed. It stops short of stating when-not to use this tool or naming an alternative 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds genuine value beyond that by disclosing what the call returns (configured server, user, notes folder settings), which is the main behavioral detail an agent would want given there is no output schema.

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: the purpose first, the return contents second. No filler, no restatement of the title or annotations.

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 zero-parameter diagnostic with no output schema, the description covers purpose, behavior, and a summary of the return shape adequately. A brief note on expected outcomes or failure modes (e.g. what an auth failure looks like) would make it fully complete.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description correctly describes a zero-input call and adds return-value context rather than misrepresenting any inputs.

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: 'Verify connectivity and credentials against the Nextcloud Notes API', which is clearly a diagnostic/health-check operation. It is distinguishable from the mutation siblings, though it does not explicitly distinguish itself from get_settings, whose territory (server/user/folder settings) overlaps with what this tool returns.

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 rather than stated: verifying connectivity and credentials is naturally a pre-flight/health-check call, but the description never says when to call it or how it differs from get_settings. No prerequisites 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?

Without relying on annotations, it discloses the critical non-atomic semantics ("rewrites each note individually and is not atomic: a partial failure leaves some notes moved") and that per-note outcomes are reported. This meaningfully extends the destructiveHint/openWorldHint/idempotentHint annotations with the failure-mode detail an agent needs before invoking.

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

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

Three sentences, front-loaded with the action and the reason for the implementation, followed by the failure semantics and the recursive option. Every sentence 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-atomic mutation with no output schema, the description covers mechanism, atomicity, failure behavior, and result reporting. Nothing material to calling 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%, and the description reinforces the recursive flag's meaning, but it adds little for `from` and `to` beyond what the schema already documents (the schema itself covers the "" uncategorized case). Adequate pairing with the schema, but no extra semantic depth.

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 and resource ("Rename a category") and immediately clarifies the non-obvious mechanism: "moving every note in it" because "The Notes API has no category rename." No sibling tool offers a rename, and the distinction from set_note_category or update_note is 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?

It gives an explicit conditional instruction for the recursive parameter ("Pass recursive=true to re-parent nested subcategories too"), which tells the agent when to set the flag. It stops short of stating when to prefer this over manually moving notes or explicit exclusions, so it is clear context rather than full when/when-not 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 the safety profile (readOnly=false, destructive=true, idempotent=true, openWorld=true). The description adds useful context: categories are created on the fly and attachments move with the note. It does not detail permissions or what specifically gets destroyed, but the added context is valuable.

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 short, front-loaded sentences with no wasted words. The primary action, special case, and side effect are stated efficiently.

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 a 3-parameter tool with low schema coverage and no output schema, the description is adequate but leaves gaps. It covers the category parameter and side effects, but does not explain the optional etag parameter, which is important 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 coverage is 33% (only the category parameter is described). The description's category guidance (empty string means uncategorized) merely repeats the schema, and neither id nor etag is explained. With low schema coverage, the description 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 and resource ('Move a note to a category') and adds two distinctive behaviors: category auto-creation and attachment movement. It is clearly distinguishable from sibling tools like list_categories or rename_category.

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?

Explains the special case of passing an empty string for uncategorized notes, but does not state when to use this tool versus alternatives like update_note or rename_category. Usage is implied rather than explicitly guided.

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?

Goes well beyond the annotations (which only flag non-read-only, idempotent, destructive, open-world) by disclosing PATCH-style partial-update behavior, the fact that 'content' destructively replaces the whole body, and optimistic-concurrency semantics via etag. These are exactly the behaviors an agent needs to avoid data loss on a mutation.

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 short sentences, front-loaded with the core action, then the destructive-content caveat, then the concurrency hint. No filler and nothing 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 6-param mutation with no output schema, the description covers update semantics, replacement risk, and conflict handling. It does not describe the response payload, but no output schema exists and the critical call-time guidance is present.

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 33%, so the description must carry weight: it explains that 'content' replaces the entire body and clarifies the etag's conflict-refusal purpose. The remaining parameters (id, title, category, favorite) are self-evident and left to the schema, which is reasonable.

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 ('Update a note') and immediately disambiguates the patch semantics with 'Only the supplied fields change.' It also names the sibling it is not (append_to_note), so an agent can route correctly without reading 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?

Explicitly routes content-appending work to append_to_note and tells the agent to pass the etag from get_note for conflict detection. It stops short of enumerating other alternatives or prerequisites (e.g. when vs set_note_category or update_settings), but the primary branching decision is covered.

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 destructiveHint=true and idempotentHint=true. Description adds valuable context: fileSuffix behavior (non-standard stored as custom), and critical warning that changing notesPath makes old notes disappear until reverted. This goes beyond annotations by explaining side effects.

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?

Efficient: one sentence purpose, then two specific parameter warnings. Front-loaded and no fluff. Could be slightly tighter but appropriate for critical warnings.

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 settings mutation with no output schema, description covers key risks (path change, suffix format). Missing: whether changes are atomic, or what happens to noteMode etc. But annotations cover safety profile, and schema covers most params.

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 80%, so baseline 3. Description adds extra detail for fileSuffix (must include dot) and notesPath (re-points), but doesn't cover noteMode, showHidden, or loadRecentOnStartUp 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?

Clear verb+resource: 'Change the Notes app settings.' Distinguishes from sibling get_settings (read vs write). However, it doesn't name read-only counterpart or differentiate from other update 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?

No explicit when-to-use vs alternatives. Implied for settings changes, but no guidance on preconditions or relationship to get_settings.

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