RemainAI

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that named notes are read in full before answering, that missing notes are reported rather than guessed at, and that the call spends the account's AI credits. These are meaningful behavioral traits that help an agent decide whether to invoke it. The cost disclosure is especially valuable for a read-only AI-powered 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?

The description is front-loaded with the core purpose, then usage guidance, cost warning, and alternative. Each sentence earns its place by adding distinct information. It is appropriately sized for a two-parameter tool with clear routing 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?

Given the simple schema, full parameter documentation, annotations, and no output schema, the description covers what the tool does, when to use it, when not to use it, cost implications, and failure behavior. Nothing essential for correct invocation 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. The description adds useful meaning by explaining that the question should contain the request in the user's own terms and that notes can be named by title or topic, with named notes read in full. It does not add details like the six-note maximum, but that is already 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?

The description states a specific verb and resource: answer a question using the user's captured material and name the source notes. It clearly distinguishes the tool from read_note by framing this as a reasoning-over-notes operation rather than a lookup. An agent can identify the tool's purpose 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?

It explicitly names the ideal use case: 'do X considering what's in my note about Y'. It also gives when-not guidance and a named alternative: use read_note for lookups or when the agent can answer from the text itself. This is close to ideal routing guidance.

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

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

Annotations only say it is a non-destructive, non-idempotent write; the description goes far beyond that by disclosing that nonexistent tags are auto-created, hashtags are stripped from saved text, tag behaviors execute and their output is returned, and that behaviors/word definitions consume AI credits and require the ai permission. Those are exactly the side effects and cost prerequisites an agent needs before calling.

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?

Front-loaded with the core action and organized into note / todo / behavior / fallback chunks, so a skimming agent still gets the gist. It is dense — the final sentence about implicit filing words is long — but nearly every clause carries operational 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?

With no output schema, the description does gesture at return values ('its answer comes back in the result', 'the result's read_as says so'), and it covers permissions, credits, and side effects well. It does not describe the general shape of a successful result (id, parsed tags, etc.), leaving a modest gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns a bump by explaining tag path syntax, tag auto-creation, hashtag stripping, and the title-derivation rule for the text parameter. The 'folder' parameter is never mentioned, which keeps it from a 5.

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 plus the exact resource kinds it creates (note, todo, word) and positions it as the write-side counterpart to the read/update siblings in the list. An agent can tell immediately this creates new items rather than modifying existing ones like 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?

Gives concrete routing rules — 'Call list_tags first when unsure which tag fits' — and explains that omitting kind/tags triggers server-side interpretation. It does not explicitly say when to prefer update_note or restore_note over capturing again, so it stops short of full alternative coverage.

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 non-read-only, non-destructive, non-open-world behavior. The description adds valuable context beyond annotations: what the note contains, that re-filing adds tags to the same note instead of creating a copy, and that missing tags are created. It does not describe permissions, errors, or return behavior, and the idempotentHint=false annotation is in slight tension with the no-copy re-filing behavior, though not a direct 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?

Three compact sentences front-load the main action and then cover the important edge cases. There is 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 simple two-parameter mutation with annotations covering its safety profile and no output schema, the description supplies the key transformation, note contents, tag-creation side effect, and repeat-filing behavior. Nothing essential for correct invocation 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%, and the schema already documents the URL source and the tag array including maxItems. The description adds behavioral meaning about tags being created if missing, but does not add parameter syntax or format details beyond what the schema provides, so the 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 and resource ('file article') and describes the concrete transformation: the article becomes a note under the given tags, holding its text, link, and summary when available. This clearly distinguishes it from read_article, list_notes, and other siblings by outcome.

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 this is for saving feed articles into tagged notes, and the schema notes the URL comes from list_feed_items. However, it does not explicitly say when to choose this over capture or update_note, nor does it state when not to use 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?

Goes well beyond the readOnlyHint annotation by disclosing that the inbox is refreshed from upstream feeds before listing (a network/side-effect behavior an agent must know about) and that view selects between inbox, saved, and history. It also adds a prompt-injection warning that article text is untrusted publisher data — valuable safety context. The only gap is it doesn't say what happens if the feed fetch fails.

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?

Front-loaded with what the tool returns, then narrowing options, then the refresh caveat, then the hand-off to read_article and the untrusted-data warning. Three sentences of dense, non-redundant 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?

With no output schema, the description compensates by enumerating the returned fields (title, source, date, summary, read/saved state), and it covers all eight parameters through schema plus narrative. An agent has everything needed to call it correctly on the first attempt.

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 baseline is 3, but the description adds genuine meaning: it clarifies the default view is the News-page inbox and explains the saved/read views in terms of user-facing concepts rather than enum labels. It does not expand on cursor or limit semantics beyond the schema.

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

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

Opens with a specific verb+resource and describes exactly what is returned: 'Articles from the user's feeds, newest first... title, source, date, the feed's own summary, and whether the user has read or saved it.' It is clearly distinguishable from read_article and list_feeds, both of which it explicitly routes to.

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 usage contexts: narrow by category/source/title words, use view "saved" for saved articles and "read" for history, and pass an item's url to read_article for full text. The refresh precondition ('unless refresh is false') is stated up front so the agent knows the side effect before calling.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful return-shape context by saying results are grouped by user-defined category and include unread counts, though it does not mention ordering or pagination 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 sentences with no wasted text. The return content and grouping are front-loaded, followed by concrete usage guidance and the sibling handoff.

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 zero parameters, basic read-only annotations, and no output schema, the description carries the right amount of detail: it explains what is returned, how it is grouped, and how to use it with list_feed_items. Nothing important 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?

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is sufficient.

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 exactly what the tool returns: the user's RSS/Atom feed subscriptions grouped by category, with unread counts. It also distinguishes the tool from list_feed_items by explaining that this tool helps identify the category or source to pass to that sibling.

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 explicit use cases: answering 'what feeds do I follow' and finding the category or source for list_feed_items. This makes the when-to-use condition and the relevant alternative clear to an agent.

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 openWorldHint=false, so the safety profile is covered structurally. The description's added value is the return shape — folder paths plus note counts — which is genuinely useful since there is no output schema. It says nothing about ordering, empty-folder handling, or nesting depth, so it adds some but not rich behavioral 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?

Two short sentences, zero filler. The result shape comes first and the follow-up routing second, which matches how an agent would read it.

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

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

For a zero-parameter read tool with no output schema, this covers what the call returns and what to do next. Minor gaps remain around ordering and whether paths are hierarchical or flat, but nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; baseline 4 applies. The description correctly implies a no-argument call by not mentioning any inputs.

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

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

Describes the resource (the user's note folders) and the shape of the result (paths like "Projects/Alpha" with a note count per folder). It is also implicitly contrasted with list_notes, so an agent can tell the two apart. It stops short of a clean verb-first statement such as "List all folders," relying on the tool name for the action word.

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 second sentence gives explicit routing: take the returned path and pass it to list_notes to see folder contents. That is a concrete when-to-use-this-and-what-next instruction. It lacks an explicit exclusion (e.g. when to prefer list_tags or search_notes), which keeps it off 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?

The annotations already cover read-only and closed-world safety, and the description adds value on top: default ordering, the id-per-row shape, cursor-based pagination via next_cursor, and the 30-day window on trash. The one soft spot is "newest first" against a sort parameter that defaults to "updated" — close enough not to contradict, but it leaves the ordering slightly ambiguous.

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 first sentence front-loads purpose and capability in one breath; the no-filter framing and pagination/trash notes follow in a sensible order. The filter enumeration runs long, but it is dense with specifics rather than padding, so it earns most of its length.

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

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

For a 14-parameter read tool with no output schema, the description covers what an agent most needs: how pages continue, that rows carry ids for read_note, and how trash mode differs. It is thin on return shape beyond the id, but with full schema documentation and the no-output-schema allowance this is close to complete.

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

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

Schema coverage is 100%, so every parameter, enum and bound is already documented in the schema itself. The description mostly re-enumerates filter categories rather than adding semantics, and its genuinely useful additions (filters compose freely, no-filter behavior, trash/restore lifecycle) are modest. Baseline 3 is the right landing point when the schema carries the weight.

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 ("Browse the user's entries") and enumerates the dimensions it can filter on, which maps directly onto the schema. It also routes onward to read_note and restore_note. It stops short of naming search_notes or list_todos, both siblings whose territory overlaps with the text filter and the done/kind filter, so the agent must infer the boundary on its own.

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?

"With no filters it is 'what have I captured lately'" gives a concrete default-use picture, and the trash branch explicitly points at restore_note as the follow-up action. What's missing is an exclusion: nothing states when to page through this list versus reaching for search_notes, even though the free-text filter makes that a live choice.

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 openWorldHint=false, and the description does not contradict them. It adds genuine context beyond annotations: the exact fields surfaced, the meaning of out_of_date (readers still see stale text), and which tool resolves it.

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

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

Three sentences, front-loaded with what is listed and followed by the field glossary and hand-offs. Dense but each clause carries information; minor cost is that the field meanings, out_of_date explanation and tool routing are packed into one long sentence.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so field by field, plus the stale-version lifecycle. Combined with annotations and the zero-parameter schema, an agent has everything needed to call 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?

Zero parameters, so the baseline is 4. The description instead spends its words on the shape of the result — title, public link, live status, reader-visible version, view/read counts — which is the relevant 'semantics' for a no-arg 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?

States a specific verb ('List') and resource ('notes the user has published on RemainAI Posts'), then enumerates the returned fields. That scope distinguishes it from the sibling list_notes, though the description never names that sibling explicitly.

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

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

Gives clear workflow routing: use publish_post_update when out_of_date is true, read_note to read the source note, update_note to edit it. It does not explicitly state when to prefer list_posts over list_notes, which is the one gap.

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 openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing what the response contains — due vs. done status plus per-ritual streak and weekly progress — which is otherwise unknowable without an 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?

A single front-loaded sentence with zero filler; the resource and scope come first and the return contents follow immediately.

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 carries the return-value burden and does so reasonably by enumerating due/done/streak/progress. Only minor gaps remain, such as whether rituals not scheduled for that day appear at all.

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 single date parameter is fully documented including its YYYY-MM-DD format and today default. The description's 'for one day' wording aligns with the schema but adds no syntax or semantics beyond it, so 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?

Names the resource (the user's rituals/recurring habits), the scope (one day), and the content returned (due, done, streak, weekly progress). An agent can distinguish it from mark_ritual at a glance, though the listing verb itself is only implied by the name rather than stated.

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 one-day scope hints at usage, but there is no explicit when-to-use guidance, no mention of prerequisites, and no named alternative (e.g., mark_ritual for updating status). The agent must infer that this is the read path for daily habit review.

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 openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context about the response: tags are returned as a slug tree, include entry counts, and indicate which tags trigger behaviors. It does not discuss pagination or size limits, so it is strong but not exhaustive.

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 compact sentences with no wasted text. It front-loads the returned shape, then gives usage guidance and the read_tag alternative.

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 listing tool with no output schema, the description sufficiently explains the returned value: a tree of slugs with counts and behavior information. Combined with the schema and annotations, an agent has what it needs to call 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?

Schema description coverage is 100%, and the sole optional 'under' parameter is fully documented in the schema as restricting to a tag and its descendants. The description does not add any further meaning beyond the schema, so the 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 clearly identifies the resource (the user's tags), the returned structure (a tree of slugs with entry counts and attached behaviors), and explicitly contrasts itself with read_tag. An agent can distinguish it from the sibling detail tool 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?

It states exactly when to use the tool — before listing, capturing, or filing into a tag — and names read_tag as the alternative for viewing one tag in detail. This is explicit routing rather than implied usage.

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

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

Annotations already cover readOnlyHint and openWorldHint, so the bar is lower; the description still adds real semantics the annotations do not carry: results are grouped by list, a list is a tag, and only open todos appear by default. Return format beyond grouping and pagination behavior are left implicit, keeping it at 4.

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: what you get, how it is shaped, the default filter, then the alternative action. The grouping/tag explanation is front-loaded and every sentence 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 three-optional-parameter, read-only list tool with no output schema, the description gives enough structure (grouped by list/tag, open-only default) for an agent to predict the result. Pagination interaction between limit and grouping is not addressed, a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description independently explains the 'list' parameter by clarifying that a list is a tag and giving the todo/groceries → "groceries" mapping, which is genuinely additive. It reinforces include_done's default behavior as well; limit is left to 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?

Names the specific resource (the user's todos) and describes the return shape ('grouped into their lists'), which is more than a restatement of the name. The tag equivalence ('a list is a tag (todo/groceries shows as "groceries")') pins down the data model. It stops short of explicitly contrasting with siblings like list_notes or list_tags, so it does not fully earn a 5.

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?

'Open todos only unless include_done is set' gives the default selection rule, and 'Use update_note with done: true to tick one off' routes the agent to the correct sibling for the adjacent write action. Lacks an explicit when-not (e.g., when to reach for list_notes instead), so 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 declare the mutation/idempotency/safety profile, and the description usefully adds the default behavior (ticks off unless done:false) and that the day defaults to the user's local today. It does not describe the response or error behavior, but with annotations covering safety this is solid added 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?

Two short sentences, front-loaded with the action and immediately followed by the identifier convention. No filler, nothing repeated from the schema.

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

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

For a 3-parameter, single-required-param toggle with full schema coverage and annotations, the description covers action, defaults, and identifier source. The only omission is what the call returns (no output schema exists), which would help an agent confirm the resulting state.

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 a genuine semantic hint not in the schema: the ritual may be named the way the user says it ('meditate') or by id, which signals fuzzy name matching. The date and done semantics are left entirely to 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 ('tick a ritual off') plus the inverse operation ('untick it'), and names the sibling list_rituals as the id source. An agent can immediately distinguish this from list_rituals 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?

Gives clear context for the inverse case ('done: false') and points to list_rituals for obtaining ids, which is the main prerequisite. It does not state any explicit when-not-to-use or edge conditions (e.g. what happens for an unknown ritual name), so it stops 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 flag this as a non-readonly, non-destructive, non-idempotent, open-world write, but the description adds the consequences the annotations cannot: the change becomes publicly visible to post readers, earlier versions persist in history and can be restored, and no new post is created. That is material context an agent needs before triggering an outward-facing mutation, and it does not contradict any hint.

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

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

Three tight sentences, each doing distinct work: what happens, when to call / when not to, and the existence precondition. The public-visibility consequence is front-loaded where it matters most for a mutation.

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 public-facing mutation with 100% schema coverage and no output schema, nothing an agent needs is missing: effect, alternatives, precondition, reversibility, and visibility are all stated. Return values are not needed since no output schema exists and none is implied.

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 parameters are already documented and the baseline is 3. The description adds a bit beyond the schema by framing the note as 'a published note's current text,' implying the note must be a published note and that saved text as of now is what gets shipped.

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?

Uses a specific verb (publish) on a specific resource (a published note's current text as the next post version) and explicitly separates itself from editing the note (update_note) and from first-time publishing. An agent can distinguish it from siblings like update_note or list_posts without opening a 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?

Gives an explicit when-to-call ('only when the user asked to publish or update the post') and an explicit when-not ('not as a follow-up to editing'), plus a precondition ('only updates a post that already exists; a note is published for the first time from RemainAI's Posts page'). This is the rare case where routing is fully 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?

Annotations already mark this as a safe read-only operation, and the description adds critical behavior beyond them: long articles are paged via more_text.offset, and the returned publisher text must be treated as untrusted data with no instruction-following. That is exactly the kind of safety and pagination context an agent needs.

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 with no waste: purpose first, eligibility second, pagination and untrusted-content warning last. The structure is front-loaded and each sentence adds operational value.

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 read tool with no output schema, the description covers source, eligibility, pagination, returned fields, and the untrusted-content caveat. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, and the schema already defines both parameters including the url source and offset continuation. The description mostly repeats those semantics, though it does reinforce that the url must come exactly from list_feed_items and that offset continues from a prior more_text.offset.

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 (read) and resource (one article), plus what is returned: full text, existing summary, and filing notes. The scope is precisely bounded to articles in the user's feeds, and the source url is tied to list_feed_items.

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?

Clearly states where the url comes from (list_feed_items) and the eligibility constraint (only articles in inbox, saved, or read). It does not explicitly name alternatives such as summarize_article or explain when not to use this tool, but the usage context is strong.

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 annotation, it discloses pagination behavior (20000-character windows, more_text.offset), fuzzy-resolution side effects (the result reports how it was found and what else matched), and an explicit prompt-injection boundary about text being user data rather than instructions. These are exactly the traits structured fields cannot express.

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, front-loaded with what is returned and then the resolution and pagination mechanics, with the safety caveat correctly placed last. The clause about a word's definition and a tag page's answer is somewhat convoluted, but it carries real information and nothing is 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?

With no output schema, the description carries the return-value burden itself and does so: it names the fields returned, the more_text marker, and the match-reporting behavior. An agent has everything needed to call it, page through long notes, and handle inexact titles.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning: `note` accepts an id from any tool's output or a non-exact title resolved by closest-match, and `offset` is explicitly tied to a prior call's more_text.offset rather than being a generic integer. The 20000-character window size quantifies the offset unit.

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?

"Read one entry in full" gives a specific verb plus resource and immediately enumerates the returned payload (whole text as Markdown, tags, folder, dates, plus type-specific extras). This clearly separates it from siblings like list_notes, search_notes, and read_tag, which return collections or different resources.

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 establishes the read-one-entry use case and, crucially, prescribes the continuation loop: "when more_text is present, call again with its offset." It also explains that inexact titles fall back to closest-title then content matching, so an agent needn't hunt for an exact id. It never names an alternative tool (e.g., search_notes to locate, list_notes to browse), which keeps it just below the top mark.

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 readOnly and closed-world safety, so the description's job is content disclosure, and it does that well by spelling out the five categories of returned data including behavior instructions and reference notes. It stops short of saying what happens for a nonexistent tag or how 'latest entries' is bounded (count, ordering).

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 resource and scope before listing contents. The trailing parenthetical about instructions and answer shape is dense but each clause maps to a real returned field, so little is wasted.

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

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

There is no output schema, so the description correctly compensates by enumerating the return payload, which is the main thing an agent needs before calling. Only edge behavior (missing tag, entry-limit on 'latest entries') 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?

With a single parameter at 100% schema coverage, the schema already documents the argument, so baseline 3 applies. The description adds nothing about accepted tag path formats (hierarchical separators, whether names resolve ambiguously), which is the one place extra meaning would have helped.

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 the resource (one tag) and enumerates exactly what the read returns: subtags, entry counts, behavior/instructions, reference notes, and latest entries. That is specific enough to separate it from list_tags, though it never states the verb explicitly and doesn't call out the sibling contrast.

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?

'One tag in detail' implies the detail-view use case versus a list view, so the usage is inferable. But there is no explicit when-to-use, no condition such as fetching a tag before capturing under it, and no named alternative among the many sibling tools.

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 is a non-destructive, idempotent mutation, so the bar is lower; the description still adds real value by disclosing that tags, folder membership, and the original id are preserved on restore. It does not cover the failure case (entry not in Trash, id collision), which leaves a small behavioral 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 sentences, zero filler, with the core effect front-loaded and the discovery pointer trailing. Every clause carries information an agent needs.

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

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

For a single-parameter restore with no output schema, the description supplies the essential effect and preservation semantics plus a discovery route. A brief note on the return value or the not-in-Trash case would close the remaining gap.

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

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

Schema coverage is 100% and the schema already states the parameter accepts an id from any other tool's output or an exact title. The description's 'under its old id' adds a little contextual meaning about what the id refers to post-restore, but does not add syntax or disambiguation beyond the schema, so 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?

Names a specific verb and resource ('Bring an entry back from the Trash') and scopes the outcome ('with its tags and folder, under its old id'). This is clearly distinguishable from trash_note and the list_* siblings without opening any 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 the agent to 'list_notes with trash: true' as the way to discover what is restorable, which is a genuine usage precondition rather than a bare restatement. It stops short of stating exclusions (e.g., what happens if the entry is not in the Trash), so it is clear context rather than a full when/when-not guide.

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 safety (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral detail beyond them: excerpt-around-hit results, the id needed for the read_note follow-up, and the exact-phrase-to-individual-words fallback. It stops short of describing ranking order or how many results a broad query yields, so not a full 5.

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

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

Purpose and scope are front-loaded in the first sentence, then return shape, then query-phrasing advice, then the sibling alternative. Four sentences with no filler and no repetition of schema constraints like the 1-20 limit.

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 carries the burden and discharges it: it states what comes back (excerpt plus id), which tool consumes that id, and how matching degrades. An agent can call this correctly and chain to read_note without further inspection.

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 baseline is 3; the description still earns a bump by adding usage semantics the schema lacks, namely that the query should be the user's own words and how a zero-hit exact phrase degrades to per-word matching.

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

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

Specific verb ('Full-text search') plus an explicitly enumerated scope ('notes, todos, saved words and the items on their tag pages'), and it names list_notes as the browsing alternative so it is distinguishable from siblings without opening a 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?

Gives explicit when-to-use guidance including a worked example of query phrasing ('what did I decide about the billing migration' -> 'billing migration') and names the alternative (list_notes) for tag/folder/date browsing, spelling out the condition that selects 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?

Annotations only cover readOnlyHint and openWorldHint, so the description adds real behavioral context beyond them: the quota/cost model (cached summaries are free, new ones consume a monthly allowance) and the fact that read_article may already carry the summary. That materially changes an agent's decision to invoke, and nothing here contradicts readOnlyHint=true – it is a read that consumes quota, not a mutation.

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

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

Three tight sentences, no filler, with the output and cost model front-loaded. The opening is a sentence fragment ('A takeaway and the key points of...') that reads slightly awkwardly but wastes no 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?

With no output schema, the description usefully states what is returned (a takeaway plus key points) and discloses the cost behavior, which is what an agent needs before spending quota. It stops short of describing summary length or failure behavior for paywalled/unfetchable URLs, a minor gap for a single-parameter 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?

There is a single required parameter with 100% schema description coverage, and the schema already tells the agent the url comes from list_feed_items. The description only reinforces the 'from the user's feeds' scoping and adds no syntax or format detail. Baseline 3 is correct when the schema carries the parameter semantics.

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 resource and output: 'a takeaway and the key points of one article from the user's feeds', and anchors it to the News page summary button. It also implicitly distinguishes it from read_article, which 'already includes a summary when one exists'. The only shortfall is that the summarizing verb is implied rather than stated up front.

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 names the relevant alternative (read_article) and the condition under which the agent should prefer it: when a summary already exists. The cost note ('an article summarized before costs nothing; a new summary counts against monthly summaries') gives a second reason to check before calling. No explicit when-not-to-use exclusion, but the routing signal is clear.

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

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

Annotations declare non-read-only, idempotent, and non-destructive behavior, and the description adds meaningful context beyond them: the entry disappears from lists and search, can be restored via restore_note for 30 days, and cannot be permanently deleted here. This is consistent with destructiveHint=false because it explicitly says nothing is deleted for good.

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?

Front-loads the action and effect, then adds reversibility and a clear usage constraint in compact prose. Every sentence contributes 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 one-parameter reversible mutation with no output schema, the description supplies the missing behavioral context—effect on lists/search, 30-day retention, restoration tool, and invocation guardrail—so an agent can call 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?

Schema coverage is 100%, and the schema already documents the single 'note' parameter as an id or exact title. The description repeats that identification guidance but adds no new syntax, formatting rules, or edge-case handling.

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 ('Move') and resource ('entry to the Trash') and explains the observable effect—disappearing from lists/search and being restorable for 30 days—so it is clearly distinguishable from restore_note and other note operations.

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 restricts invocation to cases where the user asked for it and points to restore_note for reversing the action. It does not name a non-trash alternative for related but different requests, so it is strong but not fully 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?

Annotations already declare idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real context the annotations cannot: batch composition via list_feed_items and the fact that un-saving is out of scope and must be done in the app.

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 purpose and followed by the workflow example. The trailing 'Unsaving is left to the app.' is clipped and slightly ambiguous in phrasing but carries a useful constraint.

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 3-parameter mutation with full annotations, but with no output schema the agent still cannot tell what is returned or how partial/invalid urls are handled, and whether read and saved may be set together is unstated.

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

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

Schema coverage is 100% and each parameter (read, saved, urls, including the 50-item cap) is documented in the schema itself. The description only reinforces that urls come from feeds and can be batched; it adds no format or edge-case semantics beyond that.

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 plus scope: 'Mark articles from the user's feeds as read or unread, or save them to read later, by url.' The three modes (read/unread/save) are named explicitly, and 'by url' distinguishes it from id-based mutators 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?

Gives a concrete composition recipe ('mark everything in crypto as read' is list_feed_items then this with every url) and a negative boundary ('Unsaving is left to the app'), which tells the agent not to attempt un-saving here. Lacks explicit guidance on whether read and saved can be combined in one call.

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 discloses important behavioral traits: prior text is kept in version history, edits rebuild only touched paragraphs/lists/tables, drawings and pictures elsewhere remain intact, certain edits are refused inside unsupported Markdown content, replacing whole text is refused when such content exists, and append_text always works. These details materially help an agent avoid unintended destructive outcomes.

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 dense and front-loads the core purpose before detailing edge cases, which suits a complex 13-parameter mutation tool. It is somewhat long and run-on in places, but nearly every sentence carries relevant operational 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?

Given the tool's complexity, no output schema, and mutation annotations, the description is complete enough to call correctly: it covers supported operations, selective field updates, lookup behavior, edit constraints, version history, refusal cases, and append_text safety.

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 all 13 parameters. The description still adds useful meaning beyond the schema by explaining edit semantics, whole-text replacement behavior, append_text reliability, and exact-title fallback to candidates.

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 an existing entry,' then enumerates the concrete operations such as ticking todos, renaming, editing text, tags, folders, pinning, favorite, drills, and reference marking. It also names the relevant sibling read_note and the append_text alternative, so an agent can distinguish this tool from related tools without opening schemas.

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 explicitly states that only passed fields change, that editing a note requires reading it first with read_note, and that edits are find-and-replace pairs matched against the Markdown read_note showed. It further clarifies exact-title vs id lookup and says ambiguous names return candidates rather than guessing.

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