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

Annotations only declare the generic profile (not read-only, not idempotent, not destructive), so the description carries real burden — and it delivers the key non-obvious behavior: the comment inherits the memo's visibility and space by default. It stops short of covering permissions, failure modes, or repetition semantics for a non-idempotent tool.

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 the core action front-loaded and the default-behavior caveat second. Nothing is wasted, though the parenthetical '(and space)' is slightly compressed phrasing that takes a moment to parse.

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 3-parameter, no-output-schema mutation tool, the definition covers the action and the one non-obvious default. It lacks error/edge behavior and does not enumerate what the enum values mean, but an agent has enough to invoke it correctly in the common case.

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%, below the high-coverage baseline, and the 'visibility' parameter has an enum with no per-value description. The description compensates by explaining the default inheritance behavior for that parameter, which the schema does not state; memo and content are already well documented in 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?

States a specific verb and resource ('Add a comment to a memo'), which is unambiguous and clearly separable from sibling write tools like create_memo or share_memo. It does not explicitly differentiate itself from other tools because no sibling also handles comments, so no differentiation is needed.

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 the tool applies (you have a memo and want to comment) but never states preconditions, when not to use it, or an alternative. The 'unless you set one' clause gestures at a decision the caller makes but is about parameter defaults, not usage 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely useful behavior: visibility default resolution (preference, usually PRIVATE, vs SPACE when placed in a space), inline tag handling, and that local attachment files get uploaded. It stops short of stating auth requirements or what happens on failure.

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 compact sentences, front-loaded with the core action, then conditional details (tags, task lists, visibility, attachments). Dense but each sentence carries actionable information with no filler.

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

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

For an 8-parameter mutation tool with only 1 required parameter, 88% schema coverage, and no output schema, the description supplies the defaulting rules that an agent could not infer from the schema alone. Remaining gaps (auth, error behavior) are minor given the annotation coverage.

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 already 88%, so the baseline would be 3, but the description adds semantics the schema does not: tags are appended as #tag only if not already present, and local file paths in attachments are uploaded and attached. That is meaningful clarification beyond the property 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?

States a specific verb and resource ('Create a new memo') plus the input format ('from Markdown'), which immediately separates it from update_memo, edit_memo_content, and the read siblings. An agent knows exactly what this tool produces without opening the schema.

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

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

The description implies usage through behavioral defaults (visibility falls back to preference, space placement changes visibility) but never states when to choose this over update_memo or edit_memo_content, nor any prerequisites. Context is implied rather than 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 and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: permanence and the side effect that the attachment vanishes from its memo, plus an explicit 'Cannot be undone' warning.

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 compact sentence with zero filler; the permanence warning is front-loaded and every clause carries information.

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

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

For a one-parameter destructive tool with annotations covering safety and a fully documented schema, this is nearly complete. Only minor gaps remain, such as error behavior when the attachment does not exist.

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% and the schema already documents the single 'attachment' parameter as name, id, or file URL. The description says nothing about accepted identifier formats, so it adds no meaning over the schema. Baseline 3 is correct.

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

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

States a specific verb (delete) and resource (attachment file) and adds the consequence (it disappears from its memo). This implicitly separates it from siblings like delete_memo and download_attachment without ambiguity.

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

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

Usage is only implied – an agent infers this is for removing an attachment. No explicit when-to-use, when-not, or named alternatives (e.g., it never says to use download_attachment first to archive a copy).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description adds the non-recoverable consequence ('This cannot be undone'), which is value beyond the annotations. It stops short of stating auth/ownership requirements or whether linked comments and attachments are also removed.

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

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

Two short sentences, front-loaded with the action and consequence, then the routing advice. No filler or repetition of the title.

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 one-parameter destructive tool with no output schema and annotations covering destructiveness/idempotency, the description supplies the two things an agent most needs: irreversibility and the safer alternative. It leaves unaddressed whether related artifacts (comments, attachments) are cascaded.

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% and the single 'memo' parameter is fully documented in the schema (id, resource name, or URL), so the description adds nothing about the argument. Baseline 3 applies when the schema does the work.

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 ('Permanently delete a memo') with the scope adverb 'permanently' that separates it from soft-delete siblings. An agent can distinguish it from delete_attachment and archive-style operations without opening the schema.

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

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

Explicitly names the preferred alternative ('Prefer update_memo with archived=true') and the condition that overrides it ('unless the user explicitly asked to delete'). This is exactly the when/when-not/alternative guidance that prevents accidental destructive calls.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description usefully adds the non-clobbering default ('Existing files are not overwritten unless overwrite=true'), which is the key behavioral risk an agent needs. It stops short of covering permission requirements 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?

Two short sentences, front-loaded with the action and scope, then the one safety-relevant caveat. 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?

Adequate for a simple 3-parameter tool with annotations covering safety, but with no output schema the description never says what is returned (e.g., the saved path) or what happens if the attachment does not exist or the path is invalid.

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%: save_to and attachment are documented in the schema, but overwrite carries no schema description. The description compensates by explaining overwrite's effect, so all three parameters have meaning somewhere.

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 ('Save the original file of an attachment to a local path'), clearly distinguishing the file-download action from siblings like read_attachment and upload_attachment. It does not, however, explicitly name or route against those siblings.

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

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

The purpose implies when to use it (when the raw file is needed locally), but there is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as read_attachment.

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 flag destructiveHint=true and idempotentHint=false, and the description adds real behavioral detail beyond that: the exact single-match precondition for replace and the newline joining semantics for append/prepend. It does not warn that edits are irreversible or describe failure behavior when old_text matches zero or many times, so it falls short of full 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?

Two sentences, front-loaded with the operation list and then the two subtle rules that matter most. No filler or restatement of the name/title.

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 the operations, the key preconditions and the joining behavior, which is enough to call it correctly. Minor omissions remain: no mention of permission requirements or what happens when the match fails.

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 60%, so the description has to carry weight and largely does: it explains the append/prepend newline-joining rule (including the leading "\n" blank-line trick), the exact-match-single-occurrence rule for old_text, and the replace_all override. It doesn't tie these rules explicitly to the operation parameter's other two values, but the added semantics go well beyond the bare schema.

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

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

States a specific verb (edit) and resource (memo content) and enumerates the three operations in a way that separates it from the sibling update_memo: it is a targeted edit, not a full rewrite. An agent can pick this over update_memo 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?

"Make a targeted edit without resending the whole memo" gives clear context for when this tool is the right choice versus a whole-memo update, but it never names update_memo as the alternative nor states an explicit exclusion. The guidance is clear but inferred rather than spelled out.

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?

Discloses behavior well beyond the annotations: one .md file per memo, YAML front matter contents (id, times, tags, visibility), attachments downloaded alongside, a timestamped sub-folder created in output_dir, and the critical gotcha that zip ignores filters and is re-importable. The annotations only say it is not read-only, not destructive, not idempotent, so the description is doing real work here. It could still mention whether the destination is overwritten on repeat runs.

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, no filler, front-loaded with the core action and then the format split. Every clause (Obsidian use case, front matter fields, attachment handling, filter behavior) carries information the 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 16-parameter, no-output-schema tool this covers the essential decisions: which format, what gets written, and how filters interact with each format. The remaining gap is the return value — the exact resulting path or manifest is not stated, so the agent must infer how to locate the produced files.

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 75%, and the description adds genuine meaning for the parameters that lack schema text: it gives format semantics (markdown vs zip), notes that filters are ignored in zip mode, and states the filters match search_memos. It does not annotate individual filter params, leaving that to the schema, but the format/output_dir semantics are clarified.

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 ('Back up memos to a local folder') and then splits the behavior by the two export modes, which makes it immediately distinguishable from search_memos and download_attachment. An agent can tell what this does and how the output differs by format without opening the schema.

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

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

Explicitly routes usage: format=markdown is recommended for Obsidian or offline analysis and shares filters with search_memos, while format=zip produces the official Memos archive for re-import and ignores filters. The when-to-use for each mode, plus the sibling that handles filtered queries, is named directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-openWorld, so the safety profile is fully covered. The description adds return-content context (metadata fields, linked items, comments) but no additional behavioral detail such as access requirements or behavior on missing/unauthorized memo ids.

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 that opens with the core action ('Read one memo in full') before enumerating returns. No redundant or filler text.

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

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

With no output schema, the description usefully enumerates the returned content, and annotations cover safety. The main gap is the undocumented include_comments parameter, otherwise the definition is adequate for a simple read 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 coverage is only 50%: the required 'memo' param is documented in the schema, but 'include_comments' has no description anywhere. The description's mention of 'comments' loosely hints at it but never explains the flag's name, default, or effect, so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Read one memo in full') and enumerates exactly what is returned (Markdown content, metadata, attachments, linked memos, comments). The 'one memo' phrasing implicitly separates it from search_memos, but does not name or contrast with the 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?

Usage is only implied: fetching the full detail of a single known memo. There is no explicit statement of when to use this versus search_memos (to find memos) or get_overview, nor any listed preconditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds value beyond them by disclosing the breadth of returned content (statistics, spaces, saved-view filters), which tells the agent what kind of side-effect-free aggregate call it is getting.

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 front-loaded clause ("Orientation in one call") followed by the content inventory and a one-sentence usage directive. No filler, no repetition of the title, and the highest-value information (what you get, when to call) leads.

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 no output schema, the description compensates by enumerating the return content, which is precisely what an agent needs to decide whether this call supplies the context it wants. Nothing required to invoke it correctly is absent.

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 zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object with 100% coverage, and no parameter claims in the description are missing or contradictory.

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 function (a single aggregate orientation call) and enumerates exactly what it returns: signed-in identity, instance/version, memo/task/tag statistics, recent activity, spaces, and saved views with filters. This is unmistakably distinct from the CRUD-oriented siblings (get_memo, search_memos, list_tags, etc.), which each target one resource.

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?

"Call this first when you need context" gives a clear, actionable when-to-use directive, which is strong for a zero-parameter bootstrap tool. It does not state any when-not condition or name an alternative, but there is no real alternative among the siblings for aggregate orientation, so the omission is minor.

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=false, and the description usefully adds that add is additive while set replaces the entire link list — key behavioral context beyond the annotations. It stops short of stating auth requirements, error behavior for nonexistent targets, or side effects on the target memos.

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

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

A single sentence with the resource and scope front-loaded, followed by the action semantics. Every clause earns its place and there is no filler.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers the central question of what each action does to existing links, which is adequate. It omits secondary behavior an agent might need, such as what happens with invalid or already-linked targets and whether the operation reports partial failures.

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 enum parameter 'action' has no description in the schema; the description supplies exactly that missing meaning by defining add/remove/set. memo and targets are already documented in the schema, so the description covers the gap well but adds nothing new for those two.

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 (link/manage references) and resource (a memo's references to other memos), and clarifies the in-app meaning ('shown as linked memos in Memos'). It is clearly distinguishable from siblings like update_memo or add_comment, though it does not explicitly name a sibling it is distinct from.

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 explains the three operating modes and their semantics: add keeps existing links, remove deletes the given ones, set replaces the whole list. That tells the agent which action to choose for a given intent, but there is no broader when-to-use guidance relative to alternatives such as update_memo.

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, and destructiveHint=false, so the safety profile is covered. The description adds the genuinely useful ordering behavior ('newest first'), but says nothing about pagination despite a page_token parameter, nor about how the memo scope interacts with result limits.

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

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

A single sentence carries both operating modes, the filter dimensions, and the sort order, with no filler. The primary scoping choice (one memo vs global search) 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?

For a read-only, idempotent list tool with rich annotations and no output schema, the description covers modes, filters, and ordering adequately. The only real gap is pagination/limit behavior, which an agent would need in order to page through results.

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 71%, with substantive descriptions on memo, type, creator, filename, and unlinked_only. The description reinforces the filterable dimensions (file name, MIME type, unlinked status) but adds no syntax, defaults, or paging detail beyond the schema, so the 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 (List) and resource (attachments) and spells out the two operating modes: scoping to one memo versus searching all attachments by filename, MIME type, or unlinked status. It also states the default ordering (newest first). It never names a sibling to contrast with, so it stops just short of full sibling differentiation.

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

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

The 'of one memo, or search all your attachments' construction makes the two usage contexts explicit, and the precedence rule (memo wins over other filters) is stated in the schema. There are no exclusions or pointers to alternative tools for fetching attachment content (e.g. download_attachment/read_attachment).

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, closed-world), so credit here is for added value: the description discloses that parent tags aggregate their children's counts (#work includes #work/project), a non-obvious behavioral rule not present in 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 tight sentences, front-loaded with the core action and followed by the one non-obvious rule. Nothing is padded or 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 simple, read-only tool with no output schema, the description covers what is returned (tags plus per-tag memo counts) and the aggregation rule. Only the parameter layer is left unaddressed.

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

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

Schema coverage is only 50%, and the description mentions neither parameter. The 'sort' enum lacks a schema description and gets no help from the description, though 'count'/'name' are fairly self-explanatory; the description fails to compensate for the documentation gap.

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

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

States a specific verb and resource (list tags) and narrows the scope to tags on active memos, with the returned payload described (memo counts). This is clearly distinct from the tag-mutating sibling rename_tag and the memo-oriented 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 purpose implies when you would call it (to survey tags/counts), but there is no explicit when-to-use guidance or mention of alternatives. No exclusions or prerequisites are given, leaving selection 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds genuinely useful behavior not in the structured fields: the default filter (open tasks in active memos) and the by-memo grouping with per-task numbering. Pagination/limits are left to the 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 sentences, front-loaded with purpose and output shape, then defaults and narrowing options. No filler.

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

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

For an 11-parameter, no-output-schema read tool, the description covers purpose, defaults and output grouping adequately. Minor gaps remain around pagination/return size, but annotations carry the safety profile and the schema carries the parameters.

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 every parameter is already documented in the schema itself; the description only gestures at the same filter dimensions and adds no syntax or format detail beyond it. Baseline 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 (collect) and resource (task-list items, i.e. '- [ ] …') scoped across memos, and explains the output grouping and that each task carries a number used by set_task_status. This clearly separates it from search_memos and get_memo.

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

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

Gives concrete defaults ('only open tasks from active memos') and enumerates the narrowing dimensions (keywords, tags, time range, space), plus an implicit hand-off to set_task_status. It lacks an explicit when-not-to-use or a direct comparison to a sibling like search_memos, so it falls 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 declare this as a safe, read-only, idempotent operation, and the description goes further by disclosing return behavior: images come back as viewable pictures with a ≤600px preview unless full_size=true, while text files come back as text. This is useful context beyond the structured safety 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?

Two tightly written sentences with zero waste; the core behavior is front-loaded and the sibling routing comes second. 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?

With no output schema, the description still explains what comes back for images and text, which is exactly the information an agent needs to use the tool correctly. Annotations cover the safety profile, so no essential context 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by specifying the ≤600px preview size and how full_size changes that behavior. The attachment parameter's accepted forms are already fully described in 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?

States a specific verb and resource ('Open an attachment') and directly distinguishes its output from the sibling tool by saying images return as viewable pictures and text as text. An agent can tell it apart from download_attachment without inspecting 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 names the alternative ('To store the original file locally use download_attachment'), giving a clear when-to-use-this-vs-that rule. No inference is needed to choose between viewing and storing an attachment.

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 readOnlyHint=false, but the description adds substantial context beyond that: it rewrites '#old' to '#new' in memo content, handles child tags, leaves code blocks and URLs untouched, preserves each memo's updated time, and defaults to a preview. This is rich behavioral detail that helps the agent avoid unintended destruction.

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 sentences, front-loaded with the core action and scope, then immediately covers the preview constraint. Every clause adds useful information with no filler.

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

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

For a 3-parameter mutation tool with no output schema, the description covers scope, side effects, child tags, exclusions, preservation of updated time, and the preview/dry_run workflow. Nothing essential is missing 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 description coverage is 100%, so the schema already documents from, to, and dry_run fully, including the 'without #' constraint and dry_run default. The description adds minor clarity by echoing '#old' to '#new' and reinforcing the preview behavior, but offers no new parameter-level semantics beyond the schema. Baseline 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 specific verb (rename), resource (tag), and scope (across all memos, active and archived), including child tag behavior. It clearly distinguishes rename_tag from siblings like update_memo or list_tags by focusing solely on tag renaming 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 gives clear operational guidance: 'Runs as a preview unless dry_run=false — show the preview to the user first.' This tells the agent when and how to invoke safely. It does not name alternative tools for similar tasks, which is why it's not 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 cover read-only, idempotent and non-destructive, so the description's value is elsewhere: it discloses the default result scope, the per-result shape (id, time, visibility, tags, one-line snippet), the full_content mode for Markdown, and that results are newest first. Return-shape disclosure is especially valuable because 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?

Three dense sentences covering filters, default scope, and result/pagination behavior in roughly seventy words for an 18-parameter tool, with the filter enumeration front-loaded. Nothing is padding; 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 an 18-parameter, zero-required, no-output-schema search tool, the description supplies the two things the schema cannot: what the default query returns and how to page through it. It is not fully complete because it never explains that unpaged results are capped by limit or how the advanced filter interacts, but the safety annotations cover the rest.

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 high (83%), so the baseline is 3; the schema already explains from/to formats, tag parent matching, creator defaults, CEL filter fields and so on. The description adds only a small amount of meaning beyond that (full_content being useful for summarizing, newest-first default ordering) and omits limit, sort, tag_mode, creator and filter entirely.

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+resource ('Find memos') and enumerates the filter dimensions (keywords, tags, time range, pinned state, visibility, content properties, space, saved view), which is more than a restatement of the name. It never names a sibling, so an agent must infer the boundary with get_memo/export_memos rather than being told.

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 real selection context: default scope is your own active (non-archived) memos, and archived=false/creator/space defaults are implied by the schema. It stops short of stating when NOT to use this tool or pointing at the single-memo and export alternatives, so it is clear context without exclusions.

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

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

Annotations already declare this a non-read-only, destructive, non-idempotent mutation, so the description only needs to add context. It adds the important scoping fact that exactly one item is affected, but says nothing about what happens on an ambiguous or unmatched task_text, or which behavior wins if both identifiers are passed. 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?

Two tight sentences, front-loaded with the action and immediately followed by the addressing rules. Every clause carries information the agent needs; no filler or restatement of the title.

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 4-parameter toggle with no output schema and annotations that already carry the safety profile, the description covers the essentials: what changes, how many items, and how to identify the target. The remaining gap is collision behavior when both task_index and task_text are provided, or when task_text matches multiple items.

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 75%, so the baseline is a 3; the description earns more by clarifying that task_index follows the ordering returned by list_todos/get_memo and that task_text must be a unique fragment of the item's text. It still omits any mention of the `done` flag's default or the memo parameter's accepted id forms, which the schema already covers.

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 with scope: "Mark one task-list item in a memo as done or not done." The word "one" and "task-list item" distinguish it from sibling mutators like update_memo or edit_memo_content, and it names list_todos as the source of the identifiers, so an agent can place it immediately.

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 the two alternative addressing modes (task_index from list_todos/get_memo order, or task_text) and implicitly tells the agent to obtain indices from those listing tools first. It does not state what to do when neither identifier is supplied, nor whether one mode takes precedence over the other.

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 cover the safety profile (write, non-destructive, non-idempotent, not open-world). The description adds genuinely useful context beyond that: the link grants anonymous read access, it can be made to expire or never expire, and revocation is only possible through the web UI. It stops short of describing the returned value or repeat-call 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?

Three short sentences, front-loaded with the core action and its access implication. No filler, and the revocation caveat is placed where an agent will see it before calling.

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 two-parameter mutation tool with annotated safety hints, the description covers access semantics, expiry, and the revocation path. The one omission is the return value (presumably the share URL) — with no output schema, that would have been worth stating explicitly.

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 parameters are already documented in the schema. The description only restates the optional-expiry idea without adding format guidance beyond what the schema provides; 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?

States a specific verb and resource ('Create a secret share link') and immediately qualifies the effect: anyone with the URL can read the memo without signing in. That distinguishes it cleanly from the read/write siblings like get_memo or update_memo.

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 operating context — optional expiry and the fact that revocation happens in the Memos web UI, not here. It does not explicitly say when to prefer this over another approach, but no sibling tool overlaps, so the routing risk is low.

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 flag destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds value beyond them by clarifying that content replaces the ENTIRE memo (the actual destructive act) and that unspecified fields are left untouched, which is non-obvious for a PATCH-style update. It does not mention auth/permission requirements or whether the operation is reversible beyond archive.

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 mutation scope, followed by the alternative-tool routing and the partial-update rule. No filler, every sentence carries distinct information.

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

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

No output schema exists and there are 7 parameters, but the description covers what the tool mutates, how partial updates behave, and when to prefer a sibling. The gaps are minor (no note on permission requirements or return shape), and annotations carry the destructive/idempotency profile.

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 71% and the schema already documents most fields (content replaces everything, 'none' removed from space, archived is reversible). The description reinforces the partial-update contract and highlights the full-replacement semantics of content, adding meaning to the destructive content parameter. It doesn't add syntax detail for created_at or the visibility enum, which is fine since those are schema-documented.

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 (change/update) plus the exact resource (memo) and enumerates the mutation surface: visibility, pinned, archived, space, creation time, and full content replacement. It explicitly distinguishes itself from edit_memo_content, so an agent can route 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?

Names the alternative tool (edit_memo_content) and the condition that selects it ('For small text changes prefer edit_memo_content so the rest of the memo is not rewritten'). It also sets the partial-update expectation ('Only the fields you pass are changed'), which prevents the most likely 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?

Annotations cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds real behavioral context: it discloses the return value (the attachment name) and that attaching to a memo is optional. It omits auth requirements and any note about remote fetching semantics, which is a minor gap.

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

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

Two tight sentences with zero filler; the source modes and the return value are both front-loaded. 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?

With no output schema, the description compensates by stating what is returned. Six parameters are fully covered by the schema, and the description supplies the workflow link to create_memo, leaving no critical gap 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 100%, so the schema already documents all six parameters in detail (including the filename requirement for text and MIME guessing). The description only echoes the parameter names as source modes, adding little beyond the schema's own descriptions, so the 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?

States a specific verb (upload) and resource (Memos attachment), and enumerates the three distinct source modes (file_path, url, text). This clearly distinguishes it from sibling read-side tools like download_attachment and read_attachment.

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 names the three source modes, which is the primary selection decision an agent faces, and signals a downstream workflow ('for use with create_memo'). It does not explicitly state when *not* to use this tool or contrast it against alternatives such as link_memos.

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