NoteMCP

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

Annotations only indicate that the tool is not read-only and not destructive. The description adds that it mutates an existing note by appending markdown to the end, which clarifies ordering and non-replacement behavior. It does not cover error behavior, auth, or idempotency, but those are less critical for a simple append operation.

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 captures the action, target, format, and position, with no filler or redundancy. Every element 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 append with three parameters and an output schema, the description plus annotations cover the essential operational facts. Alternative-tool guidance is absent, but nothing necessary for actually invoking the tool 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 documentation covers only if_updated_at, so the description must carry meaning for id and content_markdown. It does: id identifies the existing note to append to, and content_markdown is the markdown to append. It omits length or format constraints, but the core parameter semantics are clear for a 3-parameter 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?

The description names a precise operation—'Append markdown to the end of an existing note's body'—and the end-of-body semantics naturally separate it from update_note and replace_in_note. It clearly identifies the resource and the action.

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 verb and target imply the intended use: adding content to the end of an existing note rather than replacing or editing in place. However, the description never explicitly says when to prefer this over replace_in_note or update_note, so the guidance remains inferred.

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 show readOnlyHint=false, indicating a write operation, but the description adds valuable behavioral detail: threads are flat, continuing a continuation belongs to the same thread, and retrying with the same client_id returns the already-created note instead of duplicating. This exceeds what annotations alone convey, though it does not cover topics like auth or side effects beyond creation.

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, all purposeful and directly relevant to correct invocation. The core action is front-loaded, followed by the two non-obvious parameter behaviors. No filler or redundant restatement of 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?

The description covers the non-obvious aspects an agent needs: thread continuation semantics and idempotency. Since an output schema exists, return-value documentation is not strictly required. Minor gaps remain for title, tags, and source_url, but these are self-explanatory and do not undermine effective use 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?

Schema description coverage is 50%, with title, tags, and source_url lacking schema descriptions. The description does add meaningful semantics for parent_id and client_id—explaining thread behavior and idempotency—but it leaves the other undocumented parameters unaddressed, so it only partially compensates for the schema 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?

The description opens with 'Create a note,' which is a specific verb plus resource and accurately reflects the tool's action. It also clarifies that passing parent_id continues an existing thread, adding scope beyond the bare title, though it does not explicitly name or contrast sibling tools like append_to_note or update_note.

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 clear usage context for two important cases: pass parent_id to continue an existing thread rather than starting a new note, and pass client_id to make the call idempotent. It does not, however, explicitly state when to prefer sibling tools such as append_to_note or update_note, so it stops short of full alternative routing.

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 mark destructiveHint=true, but the description adds that it's a soft delete (recoverable) and explains the cascade behavior with continuations. This adds context beyond the annotations without contradiction.

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

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

Two sentences with zero fluff: the main action is front-loaded, followed by the cascade caveat. 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 delete operation with an output schema and annotations, the description covers the key behaviors (soft delete, cascade) adequately. The schema handles parameter details, and the output schema covers return format, so nothing critical 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?

The schema already documents cascade and if_updated_at, and the description enriches cascade by explaining its effect on threads. However, the id parameter lacks a schema description and the description doesn't address it, though it's self-explanatory. Coverage is 67%, so the description 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?

The description clearly states a specific action: 'Move a note to the trash' — a distinct resource and operation. It also clarifies it's a soft delete, adding precision and differentiating it from a hard delete or other note mutations.

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 (when you want to delete a note) and provides a condition for cascade, but it does not explicitly compare with alternatives like update or replace. The context is clear enough for an agent to know when to invoke it.

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

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

The annotations already mark this as read-only and non-destructive. The description adds valuable behavioral context: it explains that thread is ordered oldest first, that source is the canonical home for imported context, and that a note with has_photos=true cannot be rewritten whole. These details go beyond the annotations and help the agent understand side effects and constraints.

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

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

The description is five sentences but each adds value: the first defines the core behavior, then it clarifies thread ordering, field roles, image retrieval, and the patching constraint. It is front-loaded with the main purpose and remains efficient given the complexity.

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

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

The description covers the output structure, image handling, and constraints, and an output schema exists, so the agent has enough context to call the tool correctly. It addresses interactions with get_note_asset, replace_in_note, and append_to_note, making it complete for this tool's complexity.

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?

Both parameters (id and full) have descriptions in the schema, giving 100% coverage. The description does not add parameter-specific meaning beyond the schema; it mentions 'full' implicitly but doesn't explain the full=false option. Since schema coverage is complete, the baseline score of 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 clearly states the tool fetches a single note with its thread, and distinguishes it from siblings by mentioning get_note_asset for image bytes and replace_in_note/append_to_note for patching when has_photos=true. It also describes fields like label, user_text, and source, making the purpose specific and unambiguous.

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

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

The description provides explicit alternatives: it tells the agent to use get_note_asset for image bytes and replace_in_note/append_to_note for patching when has_photos=true. It also notes source.image_available as a condition for get_note_asset. However, it does not broadly contrast this tool with search_notes or list_recent_notes, so usage guidance is strong but not exhaustive.

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

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

Beyond the annotations, the description adds meaningful behavioral detail: it explains default asset behavior, the optional asset='body' selection, and that 'Images are bounded, resized, and compressed on demand.' Despite readOnlyHint=false, the text clearly indicates a non-destructive read operation, and the behavior does not contradict the annotations.

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

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

The description is compact and front-loaded with the core purpose, then efficiently covers usage timing, constraints, defaults, and output behavior. Every sentence contributes uniquely and no redundant boilerplate is present.

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 has an output schema, fully described parameters, and relevant annotations, and the description fills in the remaining context: when to invoke it, what the returned content type is, and how assets are processed. An agent has everything needed to select and call this 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 coverage is 100%, so each parameter already has a clear description. The tool description adds modest value by explaining the default asset ('the note's stored source preview') and reinforcing that URL input is not accepted, but it largely relies on the schema for parameter 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?

The description opens with a specific verb and resource: 'Return an image already associated with a stored note as native MCP image content.' It clearly differentiates this tool from text-only search/list siblings by noting that image retrieval is for visual inspection and that search/list responses remain text-only.

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 explicit guidance: 'Use this after search or list when visual inspection would help' and warns 'do not call it for every note.' It also clarifies a key constraint, 'It never accepts a URL,' which prevents a common misuse.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses meaningful behavior: bodies and imported metadata are omitted unless full=true, thread-head filtering is default, and it explains the semantics of user_text, label, and updated_at. It also clarifies that 'recent' matches the app's stream ordering, which is valuable operational context.

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

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

The description is information-dense and well-structured: it leads with the core list behavior, then the most important return-shape caveat, then field-level clarifications. Every sentence contributes something an agent needs, and the most distinctive behavior (order matching, thread heads) is front-loaded.

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

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

With a complete input schema, annotations, and an output schema, the description still adds necessary context: return-shape semantics, field meanings, and the contract for writing back updated_at. There is no missing information an agent needs to call this tool correctly in a recent-notes context.

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

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

All six parameters have schema descriptions, so the baseline is 3. The description adds extra meaning by explaining what full=true changes, what include_continuations returns, and how returned fields like updated_at and label relate to future writes. That goes beyond the schema's parameter-level coverage.

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

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

The description opens with a specific verb ('List') and resource ('the user's notes'), then pins down the exact order ('most recently touched first'). It also distinguishes the scope from siblings by stating it returns thread heads only and can include continuations, making its role clear relative to get_note and search_notes.

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 strong contextual guidance: it matches the app's stream, defaults to excluding continuations, and the include_continuations parameter explicitly says to read a thread with get_note instead. It does not, however, state when to prefer this tool over search_notes for filtered or text-based lookups, so the alternative routing is not fully 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=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns tags with live note counts, and explains the path hierarchy (e.g., 'notemcp/bug' is listed alongside 'notemcp', and searching the broader tag finds sub-tags). This goes beyond what annotations provide and helps the agent understand the tool's semantics without contradictions.

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

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

The description is three concise sentences with no fluff. It front-loads the core purpose, then adds a usage hint, then explains the path hierarchy behavior. Every sentence earns its place; it's efficient and well-structured for an agent to parse quickly.

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 parameters and an output schema available, the description sufficiently explains what the tool returns (tags with counts) and the path semantics. It covers the key behavioral nuance an agent needs to know before calling the tool. Nothing critical is missing for a list-only operation.

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

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

The tool has zero parameters, so schema coverage is trivially 100% and there is nothing for the description to document about parameters. Per the baseline for zero-parameter tools, a score of 4 is appropriate because the description doesn't need to add parameter info—it correctly focuses on the output behavior 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?

The description opens with a specific verb and resource: 'Every tag the user has, with how many live notes carry it.' This clearly states the tool's function—listing all tags with counts. It distinguishes itself from siblings like search_notes, tag_note, and untag_note, which operate on tags differently. The purpose is unambiguous and not a tautology.

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 includes explicit guidance: 'Read this before guessing a tag name.' This tells the agent to call this tool when uncertain about tag names, preventing guesswork. It also explains the path hierarchy behavior, which informs how tags can be searched later. It doesn't name specific alternative tools, but the guidance is clear and actionable, earning a 4 rather than a 5.

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 mark the operation as destructive, and the description adds valuable behavioral details: matching is literal, duplicate matches cause rejection rather than guessing, all=true is the escape hatch, and omitting replace deletes the matched text. It does not mention concurrency behavior around if_updated_at, but the schema already covers that parameter.

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 action, then moves through literal matching, an illustrative example, duplicate handling, and routing advice. Every sentence earns its place and there is no redundant or filler 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?

Given the annotations, output schema, and sibling context, the description is complete enough for an agent to invoke the tool correctly. It covers the operation, safety caveats, disambiguation strategy, and when to choose the sibling update_note, with no significant gap left to inference.

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 80%, so the schema already documents most parameters. The description adds real semantic value with the literal-match warning, a concrete checkbox example, and an explanation of when all=true is needed due to duplicate-match rejection, going beyond the raw parameter defaults.

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 and resource: 'Change one span of a note without resending the rest of it.' It clearly differentiates this tool from update_note by saying it is preferred for any edit smaller than the whole note, so an agent can identify its exact role among the 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 gives explicit routing guidance: 'Prefer this over update_note for any edit smaller than the whole note.' It also explains what to do when the target text is ambiguous ('add surrounding text or pass all=true'), giving the agent concrete decision criteria.

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 declare read-only and non-destructive; the description carries the real behavioral load: whole-word treatment for words of three characters or fewer, the auto escalation order (every word → any word → meaning), the matched field's role in distinguishing exact from relaxed results, hints on empty results, and body/source-metadata omission unless full=true. It also clarifies output-field semantics such as user_text versus imported source copy and label as the human-facing name. There is no contradiction with the annotations.

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

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

The description is long, but the tool has 16 parameters and genuinely complex semantics, so the length is earned. It is front-loaded — purpose and matching rules first, response-shape details last — and every sentence addresses a distinct concern: matching, modes, filters, empty-result protocol, body omission, and output-field meanings. No filler or repetition.

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

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

For a high-complexity tool this is complete: matching semantics, mode behavior, filter composability, the empty-result protocol, body omission behavior, and key output-field meanings (matched, hints, user_text, label, updated_at) are all disclosed. Since an output schema exists, the description goes beyond what is strictly required rather than omitting anything the agent needs 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?

Despite 100% schema coverage (baseline 3), the description adds substantial meaning the schema cannot convey: hierarchical tag matching ('notemcp' matches 'notemcp/bug/share'), prefix-from-start matching rules, the behavioral escalation of mode rather than its enum values alone, and when full=true materially changes results. These are semantics an agent could not infer from parameter names or schema descriptions.

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?

Opens with a specific verb and resource — 'Search the user's notes' — and immediately scopes the search surface: note text, tags, and the title, description and URL of saved links. Among siblings like get_note and list_recent_notes it is unmistakable which tool this is and what it operates on. The description goes well beyond restating the name.

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

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

Provides explicit tactical guidance: tags is called out as 'the right tool for a request like my #bug notes', mode pinning is explained for keyword/semantic/hybrid strategies, and empty results direct the agent to read hints instead of guessing another wording. What is missing is explicit when-not guidance against sibling tools (e.g., when to prefer get_note or list_recent_notes), so it stops just short of a 5.

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 mark the operation as idempotent and non-destructive, and the description adds useful context by stating that existing tags are preserved. This prevents an agent from assuming the tags parameter replaces the full tag list, which is valuable beyond the annotations.

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

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

Two short sentences deliver the core action and the most important behavioral caveat with no filler. The description is front-loaded and 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 an output schema and safety-related annotations, the description is mostly complete. The only notable gap is the absence of any statement about errors or preconditions, such as whether the note must exist before tagging.

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

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

The input schema has 0% description coverage, so the description must carry the semantic weight. It does convey that 'id' identifies the note and 'tags' are the tags to add, and the 'kept' clause disambiguates the merge behavior. However, it omits details like tag naming constraints, duplicate handling, and whether tags must already exist.

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: 'Add tags to a note.' It also clarifies the merge behavior ('Tags already on the note are kept'), which distinguishes it from tools like untag_note. The purpose 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 usage is implied: use this when you want to add tags to a note rather than remove or replace them. However, it does not explicitly mention alternatives like untag_note or explain when not to use this tool, so the guidance is only implicit.

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

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

The description adds meaningful behavioral detail beyond the annotations: 'Tags not on the note are ignored.' This explains how the idempotentHint manifests and prevents the agent from expecting an error for absent tags. It does not contradict the destructive or read-only hints and is a useful nuance.

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 exactly two sentences, with the primary action front-loaded and the edge case explained in the second sentence. There is no filler, no redundancy, and 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 an output schema and annotations indicating destructiveness and idempotency, the description is sufficiently complete. It covers the core behavior, the edge case, and does not require explaining the output because the output schema exists. No necessary information 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?

Given the 0% schema coverage, the description compensates for the tags parameter by identifying it as a list of tags to remove and explaining the ignore behavior for mismatches. It does not describe the id parameter in any text-only detail, though the schema provides its type and name. Overall the description adds some meaning, but id could be more explicit.

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: 'Remove tags from a note.' It also clarifies the edge behavior where tags not present on the note are ignored, which distinguishes it from sibling tools like tag_note or update_note. The purpose is unmistakable.

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 usage is implied clearly: to remove tags from a note. However, there is no explicit mention of when to use this versus alternatives such as tag_note or update_note, and no when-not-to-use guidance is provided. It is functional but leaves the agent to infer the context from the description.

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

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

The description discloses non-obvious behavior beyond annotations: fields must be named in `clear` to be emptied, empty strings are insufficient, and rewriting a photo-embedding body is refused because MCP only exposes `![photo]`. These details go well beyond the destructive/idempotent hints.

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?

Four sentences, each earning its place: purpose, field semantics, sibling routing, and the photo-refusal edge case. The most important information is front-loaded.

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

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

The description covers the tool's core semantics, its dangerous edge cases, and its alternative. The output schema and annotations handle the remaining formal details, so nothing essential is missing for an agent to invoke it 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?

The description adds crucial meaning for `content_markdown` and `clear`, including the empty-string caveat and whole-field replacement model. With schema description coverage at only 25%, it compensates for the most important gaps, though it does not explicitly explain every parameter.

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 'Replace whole fields on a note,' which names a specific action and resource. It also clarifies the update model (omitted fields unchanged) and distinguishes the tool from replace_in_note.

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 routing rule: for anything short of a full rewrite, use replace_in_note, because it cannot mangle untouched text. This directly tells the agent when update_note is the right choice and when a sibling is safer.

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