Pinto Notes

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful behavior: folders are auto-created, a note placed inside a note's folder becomes a sub-note, apps scaffold a React/TS/Tailwind project, and templates pull in app+data+note. It stops short of stating what happens when the target path already exists or whether it overwrites.

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 core purpose is front-loaded in sentence one, but the remainder is a dense run-on of parentheticals and asides. The trailing markdown/tracker convention paragraph is useful only indirectly and inflates the definition well past what a create tool 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 5-parameter mutation tool with annotations covering safety and no output schema, the description covers creation semantics across all three modes thoroughly. Remaining gaps are minor: no statement of overwrite/duplicate-path behavior, no mention of `pinned`, and no indication of what the call returns.

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 80%, so the baseline is 3, but the description meaningfully expands it: it explains how `path` is interpreted per type (title derived from name, trailing slash = folder, app note) and what `template` references. The one gap is `pinned`, which is undocumented in both description and 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 first sentence names a specific verb ("Creates") and enumerates the three resources it can produce (note, folder, app), then details each mode's path semantics. It is clear on its own, but it never contrasts itself with the close siblings "write" and "edit", so an agent must infer which one to reach for.

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 heavily implied through per-mode path examples ("Work/Acme.md", "Work/Clients/", app note path), which effectively tells the agent how to invoke each variant. However, there is no explicit when-to-use/when-not guidance and no named alternative among write/edit/move, which is where this tool's ambiguity lives.

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?

Despite annotations already flagging destructiveHint=true, the description adds substantial non-obvious behavior: deletion is soft with a 30-day retention window, sub-notes and a folder's notes/files cascade into Recently Deleted, and deleting an app specifically preserves the note and keeps the app in history. These cascade rules and edge cases are exactly the context annotations 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?

A single dense sentence with nested parentheses carries a lot of information but repeats "to Recently Deleted" three times and "for 30 days" twice, which could be consolidated. The most important behavioral fact (soft delete + retention window) is embedded mid-sentence rather than front-loaded, making it harder to scan.

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 one fully documented parameter, no output schema, and annotations covering destructiveness, the description supplies enough: entity types, cascade behavior, and retention. It omits failure modes (deleting a nonexistent path, permission requirements) but nothing essential to invoking the tool 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 description coverage is 100% and the schema's `path` description already enumerates the same entity forms. The parent description reinforces that `path` is polymorphic but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a clear verb ("Deletes") and then enumerates every resource type it accepts: note, folder, file-in-folder, app file, and app. The scope is unambiguous and the entity list maps directly onto the single `path` parameter. It stops short of naming a sibling (e.g. `restore` as the counterpart), so an agent gets no explicit differentiation against the other 11 tools.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The only usage-relevant signal is the implicit one buried in the text — that deletion is soft ("to Recently Deleted... for 30 days"), which hints at recoverability but is never framed as decision guidance. An agent must infer everything about choosing this over `move` or `restore`.

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 destructive and non-readonly behavior; the description adds rich context beyond that: read-session prerequisite, exact-match semantics, empty-string deletion, validation feedback (what broke, compile/render/test), and undoability per edit. This substantially exceeds annotation coverage.

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?

Five dense sentences, front-loaded with the core operation and scope. Every sentence earns its place by conveying constraints, behavior, or return details without redundancy.

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

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

No output schema exists, but the description explains return/validation behavior ('Answers with checks...'). Annotations cover safety, schema covers paths and parameters, and the description fills remaining gaps, making it complete for a complex destructive edit 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 100%, so baseline is 3. The description adds meaningful semantics for key parameters: old_string is exact text without line numbers, must match once unless replace_all, and empty new_string deletes. It does not add much for path beyond the schema, but overall adds value beyond structured fields.

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 ('Replaces old_string with new_string') and resource targets (note, app file, data.json, text file), making the operation clear. However, it does not explicitly differentiate itself from sibling tools like write or create, which could also modify 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?

Gives clear usage context: the item must have been read in this session, old_string must be exact and match once unless replace_all, and an empty new_string deletes. No explicit alternatives (e.g., when to use write instead) or when-not-to-use guidance is provided.

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 confirm readOnly, idempotent, non-destructive, and closed-world behavior. The description goes well beyond that by disclosing line-number formatting (cat -n), default pagination limit (2000), folder-listing behavior, text extraction from PDFs/Word/Excel/PowerPoint, image rendering, and raw base64 output capped at 10 MB.

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 but front-loaded, moving from core read behavior to pagination, folder handling, file types, and raw mode without wasted sentences. Each clause carries distinct operational information for an agent.

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 four-parameter read tool with no output schema, the description is complete enough: it explains resource scoping, pagination, file-type conversions, folder behavior, and raw output limits. Annotations already cover safety and idempotency, so the remaining gaps are negligible.

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 parameter names and basic meanings are already documented. The description adds useful semantics beyond the schema: offset is the first line, limit defaults to 2000, raw true returns the file itself as base64, and line-oriented reads behave like cat -n.

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 ('Reads') and enumerates the exact resources it can read: a note, an app file, an app's data.json, a file, or a folder listing. It distinguishes the tool from siblings by focusing on content retrieval, including line numbers and file-type-specific rendering, so an agent can tell it apart from write/list/search 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?

The description provides clear context for when this tool is useful: reading note/file contents, reading long text in parts via offset/limit, listing a folder, and handling different file types. It does not explicitly state when to use fetch instead of list or search, but the reading scenarios are clearly implied and no misleading exclusions are present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond those: it discloses that results are ordered newest-first and that authorship is attributed ('a device or an AI'), which the agent cannot learn from 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?

A single compact sentence that front-loads the core content (earlier versions, ordering, authorship). The colon-plus-list construction is slightly awkward to parse 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 carries the burden of describing what comes back, and it does so adequately: version entries, newest-first, each with an actor. It omits whether the current version is included and how limit interacts with the ordering, which are minor gaps for a read-only tool.

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

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

Schema description coverage is 100% and the path parameter is exhaustively documented with examples. The description contributes only the 'newest first' ordering and says nothing about the limit parameter or pagination, 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 resource (earlier versions of a note's text, an app's code/data, or a file) and scopes it clearly, which separates it from siblings like fetch or list. However, it never uses an explicit verb ('list', 'retrieve', 'show'), so the agent must infer the operation from the noun phrase, keeping it just short of 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?

There is no statement of when to call this tool versus alternatives; the obvious comparison to the sibling restore (which presumably acts on a version) is never made. The 'newest first' ordering hints at inspection use, but no condition, prerequisite, or exclusion is 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 cover readOnly/idempotent/non-destructive safety. The description goes beyond them by disclosing ordering ('newest first'), the exact scope of pattern (every path below the given path), and that results paginate via limit/offset. It does not discuss auth or rate limits, but the added behavioral context is meaningful.

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?

Telegraphic and front-loaded: the core behavior and ordering lead, followed by path forms, pattern scope, and pagination. Every clause carries information, though the fragmentary style reads more like notes than prose.

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 annotations covering safety and no output schema, the description supplies what an agent needs: ordering, path semantics, glob scope, and pagination. It stops short of hinting at the returned entry shape, a minor omission for a list tool with 4 optional params.

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

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

Schema coverage is 100%, so the baseline is 3, but the description exceeds it: it explains each path variant with concrete examples ('Work/', 'Work/Acme/', 'Work/Habits.app') and clarifies pattern semantics ('**/*.md', 'Work/**', '**/*invoice*') beyond the schema's terse 'A glob, like "**/*.md"'. This materially improves correct invocation.

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: 'Lists like a file browser, newest first.' An agent immediately understands the operation and its ordering semantics. It stops short of differentiating itself from sibling 'search' or 'fetch', which is the only gap.

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 implicitly guides usage by enumerating the valid path forms (folder, note's folder, app, Recently Deleted) and the meaning of pattern as a glob over everything below the path. However it never states when to use list versus search or fetch, nor any when-not condition. Usage is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered; the description adds real behavior beyond that: the destination folder is created if missing, moving into a note's folder converts the target into a sub-note, and renames preserve the file ending. The one notable gap is collision handling — with destructiveHint=true, an agent would want to know whether moving onto an existing name overwrites 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?

It is front-loaded with the verb+resource, then enumerates destination forms with semicolon-separated clauses so each one is scannable. The single run-on sentence is dense but every clause carries distinct semantic content; only mild structural improvement (e.g., bullets) would help.

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 2-parameter, no-output-schema mutation tool with annotations already declaring the safety profile, the description covers target types, destination interpretation, auto-creation, and naming rules. The missing piece is failure/collision behavior and any permission requirement, which matters given destructiveHint=true.

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's terse "Where it goes." for `to`: a trailing slash means a folder, a bare name means a rename, and the ending is preserved. It also clarifies the `path` format by tying it to how list and search render paths, which the schema only partially does.

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 gives a specific verb pair (moves or renames) and enumerates the exact resource kinds affected: notes, folders, app files, and files within folders. Each move form is instantiated with a concrete example path, which lets an agent distinguish this from `edit`/`write`/`create` 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 implicitly shows usage through the destination patterns (trailing slash = into a folder, `.md` = rename, note's folder = sub-note), which is more than nothing. However it never states when to prefer `move` over siblings like `edit` or `create`, nor any when-not condition or prerequisite. Usage is inferable from examples only.

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 carry the behavioral profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds only the placement detail ('top of the list'). It never explains what the destructive hint means here (e.g., whether unpinning displaces or removes an existing pinned position) or why pinning is considered destructive, leaving the most consequential behavior unexplained.

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 short sentence that front-loads the primary action ('Pins a note to the top of the list'). The trailing 'or unpins it' is largely redundant with the 'pinned' parameter's own schema description, a small amount of wasted text in an otherwise tight definition.

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 tool with a rich path schema, full annotations, and no output schema, the description is minimally sufficient. It omits the scope question of what kinds of items can be pinned and the effect of pinning on ordering for folders versus notes, but nothing critical to a correct call 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 description coverage is 100%, so both 'path' and 'pinned' are fully documented in the schema, which sets the baseline at 3. The description adds nothing beyond the schema and in fact says 'a note' while the path schema explicitly accepts folders, sub-notes, files, and app files, slightly narrowing the apparent scope.

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 ('Pins a note to the top of the list, or unpins it') and captures the toggle nature of the operation, so the agent knows exactly what happens. It does not distinguish this tool from siblings like move or edit, which could also alter list ordering, so it stops short of 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?

Usage is only implied: the paired 'or unpins it' plus the boolean parameter makes the pin/unpin choice inferable, but there is no explicit when-to-use, no statement of prerequisites, and no named alternative (e.g., move) for repositioning content.

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 (restoring overwrites current state), so the safety profile is carried by structured data. The description adds some context via "code and data as they were," implying a revert, but does not explicitly warn that current content is replaced or describe reversibility.

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 dense sentence with the core behavior front-loaded and zero filler. The layered colon construction is slightly harder to parse than a two-sentence split would be, but nothing 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?

For a two-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description adequately conveys what can be restored and how version presence changes behavior. It stops short of stating that restoration replaces current state, which is the main 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%, so baseline would be 3, but the description adds real meaning: omitting version restores from Recently Deleted while supplying a version restores from history. That ties the optional version parameter to a concrete behavioral branch beyond the schema's bare "A version from history."

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 ("Brings back") and enumerates the exact resources: a note or file from Recently Deleted, or an earlier version of a note's text, an app, or a file. This is unambiguous and clearly distinct from siblings like delete, create, or history.

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 parenthetical "(no version)" versus the version path implies the two usage modes, so an agent can infer which to pick. However, no sibling tools are named and no explicit when-not or prerequisite guidance is 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds substantial behavior beyond that, including result ranking, snippet inclusion, paging semantics via limit/offset, path scoping forms, and opt-in inclusion of Recently Deleted. It does not describe error behavior for missing/invalid patterns or the combined-use rules for query and pattern.

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 two modes before the filter list, and every clause carries information. It is dense to the point of being a run-on in the filter enumeration, but nothing is redundant with the name or 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 15-parameter, zero-required tool with no output schema, the description covers both modes, all output shapes, scoping, filtering, and pagination. An agent can call it correctly without consulting anything else, with only the no-argument and mode-conflict edge cases unspecified.

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 already 93%, so a baseline of 3 applies, but the description adds real meaning: query syntax (words, "quoted phrases", OR, -word), the three output values and their shapes (paths, path:line: text with context, count), concrete path forms, and the YYYY-MM-DD date format. Only the boolean flags like pinned and case_sensitive 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 ('Finds notes') and then breaks the tool into its two distinct operating modes, query-based ranked full-text search and pattern-based grep, which lets an agent distinguish it from siblings like list and fetch. The scope of matching (names, paths, text) is spelled out.

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 effectively explains when to use each mode: query for ranked full-text, pattern for line-by-line regex matching, and conditions for the output parameter ('with pattern'). It does not, however, say when to prefer this tool over list or fetch, nor what happens if neither query nor pattern is supplied.

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

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

The description adds rich behavioral detail beyond annotations: it specifies operation on a throwaway copy, lists exactly what steps return (screens, console errors, data changes, screenshots), enumerates supported step actions with syntax, and confirms nothing is written back. Annotations cover safety, but the description explains the interactive simulation behavior fully.

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 but front-loads the core output then details steps, with no wasted sentences. The step examples are compact and informative, though the long parenthetical could be slightly more structured for readability.

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

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

Given no output schema, the description fully specifies return content and step behavior. Combined with annotations and a 75%-covered schema, it provides all necessary context for an agent to call the tool correctly, including safety implications.

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 baseline is lower, but the description compensates by defining step syntax and semantics (e.g., tap, type, scroll) and clarifying that steps act on a throwaway copy. It adds meaning beyond the schema's high-level parameter descriptions, though some details like step limit (30) are in schema, not description.

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

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

The description clearly states it produces screenshots of a note's app at specified sizes/themes with diagnostics, and optionally drives the UI via a steps array. It's specific about the resource (app/note) and outputs, but doesn't distinguish itself from siblings like fetch, search, or history beyond the screenshot focus.

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

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

Usage is implied by listing modes (screenshot mode vs. steps mode) and by the schema field 'on a throwaway copy', but there's no explicit guidance on when to choose this over alternatives or prerequisites for using steps. An agent must infer context.

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 readOnlyHint=false, and the description adds substantial value beyond them: the old version stays in history (recoverability), a hard 10 MB limit, the file/content_base64 selection rule, and the fact that the call returns validation checks (broken note refs, compile/render/test results).

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 dense with actionable detail — no filler sentences. It runs long and crams markdown/tracker syntax into one clause, 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 compensates by describing the return payload (checks, compile/render/test results), the replace semantics, history retention, size limits, and the note-data format including checklists, links and tracker table syntax. An agent has enough 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 coverage is 100%, so the baseline is 3, but the description adds real discriminator meaning: `file` (from chat) versus `content` for text versus `content_base64` with `mime_type` for binary, plus the 10 MB ceiling. The path examples are somewhat redundant with the schema description.

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 — writes a whole note, app file, data.json or file, creating or fully replacing it. This clearly separates it from an incremental edit, but it never names the `edit` or `create` siblings explicitly, so sibling differentiation is left to inference.

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

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

It gives an important precondition (an existing item must have been read in this session) and implicitly contrasts whole-replacement with partial editing. However, it never states when to prefer `create` or `edit` over `write`, so the agent must infer the routing.

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