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

With no annotations, the description carries the full behavioral burden and does surprisingly well: it discloses the output format, the locked-note edge case (body withheld, title plus explanation returned), and the failure profile (403/404 mirroring get_note). It omits auth requirements and any note about side effects, but for a read/export operation the edge-case and error disclosure are genuinely useful.

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

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

Three dense sentences, each earning its place: output shape, edge case, error profile. The opening is slightly noun-phrase heavy rather than verb-first, but 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?

An output schema exists so return values need not be explained, and the description still covers format, the locked-note case, and error codes. The main gap is the undocumented input identifier and the unexplained mechanics of the 'password' behavior, which is mentioned without saying how a caller supplies one.

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 0% and the description says nothing about note_id — not even that it is the same identifier accepted by get_note. The parameter name is largely self-explanatory, but the description does not compensate for the complete absence of schema documentation as the guidance requires.

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 specifies the resource and the exact output ('a single note rendered as a standalone Markdown file ... title as an H1, followed by the body'), and the word 'single' implicitly contrasts with the bulk sibling export_notes. It never names export_notes explicitly, so the differentiation is inferable 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?

There is no explicit when-to-use guidance or routing to alternatives, even though export_notes (plural) is a close sibling. The description describes behavior of the operation but never says under what conditions an agent should pick this tool over get_note or export_notes.

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?

With no annotations, the description carries the burden and does well: it discloses the exact output encoding of both formats and the non-obvious rule that locked notes are included with their body withheld. It stops short of stating permission/auth requirements or whether the default limit of 5000 truncates silently.

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?

Roughly four dense sentences with the purpose and the sibling exclusion front-loaded, then format details, then the locked-note caveat. Every sentence earns its place, though the parenthetical mechanics of format="ndjson" read slightly cramped.

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?

An output schema exists, so return structure need not be restated, and the description covers purpose, alternatives, format behavior, and locked-note handling. The gap is filter semantics for tags/tag_match/folder_id/limit, which are left entirely to defaults.

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 0%, so the description must compensate, and it only does so for 'format', which is explained thoroughly (ndjson one object per line vs markdown concatenated '# Title' blocks). The other four parameters -- tags, tag_match (a string with no enum, so 'any'/'all' semantics are unclear), folder_id, and limit -- get no explanation anywhere.

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 ('Bulk export of the caller's active notes') plus the scope that separates it from paged retrieval. It explicitly contrasts itself with list_notes, so an agent can route between the two 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?

Gives explicit when-to-use ('backups/scripting'), when-not ('not paged browsing'), and names the alternative ('use list_notes for that'). No inference is required to pick the right tool.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that the URL is short-lived and expires, and that for ZK/Vault/lock-encrypted notes the bytes at that URL remain opaque ciphertext with no decrypt path. It does not cover auth/permission requirements or whether the URL is single-use, but the expiration and encryption caveats are real behavioral value.

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, purpose first and the encryption caveat second, with no filler. The ZK/Vault/lock-encrypted phrasing is dense jargon, but each clause conveys distinct information.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description covers the critical caveat an agent would otherwise miss. Remaining gaps are permissions and error behavior for locked/encrypted notes, which are secondary for a URL-minting 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 0%, so the schema provides no meaning for note_id or attachment_id. The description implies a one-note-to-one-attachment relationship and that a URL is produced per attachment, but it never explains the identifier formats or the failure mode when note_id/attachment_id don't match.

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 specific resource (a single attachment's file bytes) and the exact artifact returned (a short-lived signed URL), and it clarifies that the download itself happens outside this tool. That scope distinguishes it from sibling reads like list_attachments and get_note without opening either schema.

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

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

The phrase 'directly (not through this tool)' implies the usage pattern, but there is no explicit when-to-use, no named alternative (e.g., list_attachments to discover attachment_id), and no stated prerequisites. Usage is inferable but not 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action and gives no information about error handling, permissions, read-only nature, or what happens if the folder is not found. This leaves the agent with significant uncertainty.

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 a single sentence of six words, completely front-loaded with the action and resource. Every word contributes value with no redundancy.

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

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

Given the simplicity of the operation and the presence of an output schema, the description is nearly sufficient. However, it does not mention behavior when the folder does not exist or when access is denied, which could be relevant for error handling.

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

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

The schema has a single parameter with 0% description coverage. The description's 'by id' adds minimal context, indicating that folder_id is the identifier, but it does not explain format, constraints, or usage beyond what the schema's title already conveys.

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 uses a specific verb ('Get') and resource ('folder') with a clear identifier ('by id'), clearly distinguishing it from sibling tools like list_folders and get_note. It immediately conveys the tool's function.

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

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

The phrase 'by id' implies this is for retrieving a single known folder, but there is no explicit guidance on when to use it versus alternatives like list_folders. No exclusions or alternative recommendations are 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses pagination semantics (cursor round-trip, None means exhausted) and an access gate (requires a Pro plan, same as the web app's Global Graph). It omits any note about response size, rate limits, or why locked notes are included.

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

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

Three dense sentences with the core scope front-loaded and no filler; each sentence adds a distinct fact (scope, pagination, access gate). Minor awkwardness in the parenthetical "(in or out) or is locked" but overall tight.

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?

An output schema exists, so return structure need not be explained, and the description covers scope, pagination, and the plan gate. The remaining gap is the undocumented limit parameter, which is a minor but real omission.

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

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

Schema description coverage is 0%, so the description must compensate. It explains cursor semantics well ("pass the response's next_cursor back in") but says nothing about the limit parameter, its default of 100, or any bounds, leaving half the parameters undocumented.

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 ("Whole-account link graph") with clear scope ("nodes and edges across every note that has at least one link (in or out) or is locked"). It implicitly distinguishes itself from per-note siblings like get_note_graph and get_note_backlinks by emphasizing "whole-account," but never names an alternative explicitly.

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

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

Usage is implied by the "whole-account" scope rather than stated: an agent must infer that this tool is for account-wide graphs and the per-note siblings for local ones. Pagination guidance (pass next_cursor back) is given, but there is no explicit when-to-use/when-not framing or named alternative.

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?

With no annotations, the description carries the full burden and does so well: it discloses the Pro-plan gate and the notable behavior that 'on a very large graph the response may note that a cheaper approximation was substituted'. It does not mention latency, rate limits, or cost of the expensive algorithms, which are the remaining meaningful behavioral gaps.

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 purpose, then parameters, then gating, then the approximation caveat — a logical ordering with no filler sentences. It is dense and slightly run-on, but every clause carries distinct information.

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

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

For a 2-parameter tool with an output schema (so return values need no explanation) and no annotations, the description covers purpose, algorithm options, plan gating, and the approximation caveat. The missing piece is explicit differentiation from the sibling graph tools.

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

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

Schema description coverage is 0% and neither parameter declares an enum, but the description enumerates every accepted value for community_algo and centrality_algo and marks the defaults. This fully compensates for the schema gap, leaving only minor omissions such as value-specific tradeoffs.

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

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

States a specific verb+resource: 'Community detection + importance ranking over the caller's whole account graph'. The scope phrase 'whole account graph' implicitly separates it from note-level graph siblings like get_note_graph, though the distinction is never made explicit. An agent can tell what it does but must infer why it differs from the other graph 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?

The description names a prerequisite ('Requires a Pro plan, same gate as get_global_note_graph') and lists algorithm choices, which hints at when the tool is applicable. However it never says when to prefer this over get_note_graph, get_global_note_graph, or get_related_notes, nor when-not to use it. Usage is implied rather than stated.

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?

With no annotations, the description carries the responsibility for behavioral disclosure. It explicitly reports 403 for non-ownership and 404 for non-existence, giving valuable error semantics. This goes beyond a simple 'get' and is sufficient for a read operation.

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

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

The description is two sentences, front-loaded with the operation, and every sentence contributes useful information (action and error behavior). No fluff.

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 simplicity, an output schema exists, and the description covers the key behavioral aspects (ownership, errors). It could mention return format, but the output schema handles that. Overall, it's complete for a single-note retrieval.

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

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

The schema's note_id parameter has no description, so the tool description's 'by id' adds some context. However, it does not specify the format or constraints of the ID, leaving room for interpretation. For a single parameter, this minimal addition is adequate but not robust.

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

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

The description clearly states the tool retrieves a single note by its ID, using a specific verb and resource. This distinguishes it from sibling tools like list_notes and search_notes, making the purpose unambiguous.

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

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

The description implies the use case—when you have a note ID—but does not explicitly mention alternatives or exclusions. It provides context through error conditions but lacks explicit guidance on when to choose this over sibling listing/search 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?

With no annotations, the description carries the full burden and does disclose real behavioral traits: 403 when note_id isn't owned by the caller, 404 when it doesn't exist, plus the per-item return shape. It is missing whether this is purely read-only and any pagination/limit behavior, which keeps it from a 5.

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

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

Two tight sentences: purpose and output shape first, error conditions second. No filler, no restatement of the tool name, everything front-loaded.

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

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

For a single-param read tool with an output schema present, the description covers purpose, return fields, and failure modes adequately. Minor gaps (pagination, explicit read-only confirmation) remain, so it is slightly short of fully complete.

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

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

Schema coverage is 0% and the single param has no schema description, so the description must compensate. It clarifies that note_id is the note being linked TO and adds an ownership precondition, which is meaningful but partial — no format/type detail beyond the schema's 'string'.

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

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

States a specific verb+resource: 'List notes that link to note_id' — the incoming-link semantics distinguish it in substance from siblings like get_related_notes or get_note_graph. It also names the return fields (id/title/snippet). It does not explicitly contrast itself with any sibling, so it falls 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 explicit when-to-use or when-not-to-use guidance, and no alternative tool is named (get_related_notes, get_note_graph, get_note are all plausible neighbors). Usage is only inferable from the phrase 'notes that link to note_id'.

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?

With no annotations, the description carries the full burden. It discloses the result shape and the hop-expansion behavior, which is real value, but says nothing about read-only safety, cost/latency of hops=2 traversal, graph size limits, or handling of locked notes.

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 dense sentences: the first defines the output and the second defines the parameter semantics. Nothing is repeated and the core concept is front-loaded.

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

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

An output schema exists, so return values need not be re-explained, and the description nonetheless sketches the node/edge shape. The hops semantics complete the parameter story; only traversal boundaries and mutation/safety posture are unaddressed, and the latter is low-risk for a read tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the non-obvious parameter: hops=1 means direct neighbors only while hops=2 expands each neighbor's neighbors one level further. note_id is covered as the graph center. Only minor gaps remain (behavior for hops > 2).

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 ('Local link graph centered on note_id') and enumerates what is returned (nodes with id/title/locked, edges as source -> target), so the agent knows exactly what it produces. 'Local' implicitly contrasts with get_global_note_graph, but no sibling is named explicitly.

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

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

Usage is only implied: the hops explanation hints at scope tradeoffs, but there is no statement of when to prefer this over get_note_backlinks, get_related_notes, or get_graph_analysis. An agent must infer routing from the word 'local' alone.

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?

With no annotations, the description carries the behavioral disclosure burden. It clearly discloses what the tool returns: active note count, storage bytes, pinned count, and a daily created-at histogram. It does not mention edge cases like how 'active' is defined or whether any filtering applies, but the 'get/stats' framing communicates a non-mutating aggregation operation.

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

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

The description is a single front-loaded sentence. It opens with 'Aggregate stats' to immediately orient the agent, then lists each returned metric in a compact, scannable structure with 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 zero-parameter tool with an output schema, the description is largely complete: it names all major result categories. It leaves minor ambiguity about the exact definition of 'active' and the time range of the histogram, but these are likely covered by the structured output schema and do not block correct tool selection.

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

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

The tool has zero parameters, so the input schema imposes no burden. The description appropriately focuses on the nature of the computed statistics rather than argument details, which is the correct emphasis for a zero-parameter endpoint.

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

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

The description clearly states the tool's purpose with a specific verb and resource: aggregating note statistics. It enumerates exact metrics (total active notes, storage bytes, pinned-note count, created-at histogram), which clearly distinguishes it from sibling tools like list_notes or get_note that handle individual records.

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 guidance on when to use this tool versus alternatives. The phrase 'Aggregate stats' implies it is for high-level overviews, but the description does not name alternatives or provide when-not-to-use criteria, so usage context is only implied.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the returned information and the 404 condition for non-Team-plan callers, but does not mention permission requirements, rate limits, or confirm read-only behavior beyond the verb 'Get'.

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

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

Two tightly written sentences front-load the resource and its scope, then add the error condition. Every clause contributes useful information 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?

With no parameters, no annotations, and an output schema present, the description is nearly complete for a zero-argument read tool. It adds the 404 behavior and field list, though it omits any explicit routing to sibling tools or permission requirements.

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 correctly describes no input arguments and instead focuses on the resource and its returned 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?

The description states a specific verb ('Get') and resource ('caller's Team-plan organization') and enumerates the returned fields, making the tool's purpose clear. It distinguishes itself from siblings like list_organization_members by focusing on the organization object rather than members, though it does not explicitly name that sibling as an alternative.

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 a useful precondition: it 404s if the caller does not belong to a Team-plan organization. However, it gives no explicit guidance on when to prefer this tool over list_organization_members or other organization-related tools, leaving usage largely implied by the resource name.

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?

With no annotations, the description carries the burden well: it discloses the Pro-plan requirement, the 403 ownership failure, the 404 missing-note failure, and that results are ranked by a similarity score with shared tags. It stops short of stating that this is a read-only operation with no side effects and says nothing about result size or pagination beyond the implicit limit.

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

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

Three tight sentences, front-loaded with the core purpose followed by gating and error conditions. The opening phrase 'Tag/link-similarity ... suggestions' is slightly awkward but dense rather than padded.

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 read tool with an output schema (so return shape needn't be explained), the description covers purpose, access gating, and both error modes. The only meaningful gap is the unexplained limit parameter, which is a schema/description failure rather than a missing behavioral note.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It clarifies note_id as the anchor note whose related items are returned, but never explains the 'limit' parameter (default 5, cap, whether it truncates ranked results) or note_id's expected format/id source. Half the parameters remain undocumented.

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 result: ranked 'you might want to link these' suggestions of other notes/canvases with shared tags, anchored on note_id. It also gestures at how it relates to siblings by naming note_graph/note_backlinks, but only in the context of the plan gate rather than stating the conceptual difference (similarity suggestions vs. fixed structural relations).

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?

'you might want to link these' suggestions clearly signals the use case (discovering potential links), which is enough for an agent to pick this over list_notes or search_notes. However, it never explicitly says when to prefer this over get_note_backlinks or get_note_graph, so the selection logic is left to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the meaningful failure modes: 403 when note_id is not owned by the caller and 404 when it does not exist. It does not mention pagination, ordering, or result limits, so it is strong but not complete.

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, the primary purpose front-loaded, and the error conditions following immediately. Every clause carries information an agent would otherwise have to discover by failing a call.

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?

An output schema exists, so return values need not be described, and the description covers purpose plus the two failure conditions. The only gap is result-set behavior such as pagination or ordering for a tool that can plausibly return many attachments.

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

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

Schema description coverage is 0% for the single note_id parameter, so the description must compensate. It does add important meaning — that note_id must be owned by the caller and must exist — but never defines what the identifier is or its format, leaving part of the parameter semantics unstated.

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

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

States a specific verb and resource ('List a note's file attachments') and scopes it to the caller's note, which cleanly separates it from the related but distinct get_attachment_download_url sibling. It stops short of naming any alternative tool, so it is clear but not differentiating in the way a 5 requires.

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 use case is implied by the resource it operates on, and the 403/404 notes tell the agent when the call will fail, but there is no explicit guidance on when to prefer this over get_note or get_attachment_download_url. That is minimum-viable implied usage rather than real routing advice.

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?

With no annotations, the description must carry the burden of behavioral disclosure. It only states that it lists folders, without addressing whether trashed items are included by default, pagination, ordering, or any side effects. No annotation contradiction exists.

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 a single sentence that is front-loaded with the action and resource. No wasted words; it is appropriately concise for a simple list tool.

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

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

The tool is simple, but the description leaves out important context: it does not mention whether the list is limited to non-trashed folders (though the schema default implies it), return format details, or any pagination/limits. An output schema exists, but the description does not reference or support it.

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

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

Schema description coverage is 0% (the description does not mention 'include_trashed'). The description fails to compensate for this low coverage, adding no meaning beyond the schema's own name and default. The agent receives no extra context about the parameter's 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 uses a specific verb ('List') and resource ('the caller's notebooks/folders'), clearly distinguishing it from siblings like 'get_folder' (single folder) and 'list_notes' (notes, not folders). The scope is explicit.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate.

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?

With no annotations, the description carries the full burden. It adds the important constraint that the note must be owned by the caller, which is a behavioral trait. However, it does not disclose what happens for non-owned notes (e.g., error vs. empty list) or any other side effects. The verb 'List' implies read-only, but that is not made explicit.

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 a single, front-loaded sentence with no fluff. Every word contributes to clarifying the tool's purpose and the key constraint. It is appropriately concise for a simple list operation.

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 there is only one parameter, an output schema exists, and the tool is straightforward, the description is largely complete. It covers the essential purpose and the ownership constraint. It lacks detail on error handling or return format, but the output schema likely handles the latter. For the simplicity of the tool, this is sufficient without being overly verbose.

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

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

The schema provides a bare 'note_id' string with no description, so the tool description must compensate. The description clarifies that the note must be owned by the caller, adding meaning to the parameter. It does not specify format or additional constraints, but for a single required parameter, the added ownership context is valuable and mostly 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 uses the specific verb 'List' and the resource 'who a note (owned by the caller) has been shared with.' It clearly distinguishes this from sibling tools like list_notes (which lists one's own notes) or list_shared_notes (which likely lists notes shared with the caller). The ownership constraint is explicitly stated, making the purpose unambiguous.

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

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

The description gives clear context: use this when you need to see the sharing recipients of a note you own. It does not explicitly name alternatives or state when not to use it, but the specificity of the description implies the appropriate situation. Since it lacks exclusions or explicit alternative references, it falls 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?

With no annotations, the description carries the full burden and does disclose several non-obvious behaviors: the empty-string vs omitted folder_id distinction, the active/trashed status values, tag OR-vs-AND semantics, and that locked notes appear with a null body. It does not mention pagination (limit/start_after) or result ordering, which for a listing tool is a notable omission.

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 tight sentences, no filler, and the core operation is front-loaded. Each sentence carries distinct information about filter behavior, so nothing needs to be cut.

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?

An output schema exists, so return-value explanation is not required, and the description covers the semantically tricky filters plus the locked-note edge case. It is still incomplete for a 7-parameter list tool: pagination and ordering parameters receive no mention, and no sibling is referenced for routing.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the tricky cases for folder_id, status, tags and tag_match, but leaves limit, pinned and start_after completely unexplained, meaning three of seven parameters have no semantic guidance anywhere.

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?

"List the caller's notes" gives a specific verb and resource, and "caller's" scopes it to the authenticated user's own notes rather than shared ones. It does not name the adjacent sibling list_shared_notes or search_notes to explain the boundary, so 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?

The description explains filter semantics (empty folder_id vs omitted, status values, tag_match modes) which tells an agent how to use it correctly, but gives no explicit when-to-use versus search_notes / list_shared_notes / list_folders. Usage is implied rather than routed.

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?

With no annotations, the description carries the full behavioral burden, and it does disclose a genuinely non-obvious trait: a plain member sees only their own entry because other members' emails/names/roles are admin/owner-only. It omits other behavior such as pagination, ordering, or error conditions when the caller is not in an organization.

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

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

Two tight sentences, front-loaded with the action and followed by the permission caveat. No filler, no redundancy, nothing that fails to earn its place.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the main gotcha (permission-scoped visibility). Given a zero-parameter, no-annotation read tool, this is nearly sufficient; only edge-case behavior (no org membership, empty result) is left unstated.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond the schema. No parameter meaning is lost or misstated.

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

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

States a specific verb and resource ('List the caller's organization's members'), which is unambiguous and clearly distinct from sibling get_organization. However, it never names or contrasts with any sibling tool, so the differentiation is only implicit through the resource noun.

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

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

Usage is implied by the name and the scoping sentence, but there is no explicit when-to-use guidance, no mention of get_organization as the alternative for org-level details, and no stated preconditions (e.g., what happens if the caller has no organization).

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?

With no annotations provided, the description carries the burden. It adds meaningful behavioral context: the scope is 'received copies' and the order is 'most recently shared first'. However, it does not disclose other traits such as read-only behavior, pagination, or authorization requirements, though these may be implied by 'list'.

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 a single sentence that is front-loaded with the verb and resource, states the scope, and specifies ordering. Every word earns its place; there is no redundancy or 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 simple, parameterless list tool with an output schema, the description adequately explains the purpose and key behavior (received copies, sorting). It does not mention edge cases like empty results or pagination, but given the simplicity and presence of an output schema, it is sufficiently complete. Slightly lower than 5 because it lacks explicit guidance on alternatives.

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

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

The tool has zero parameters and schema coverage is 100%, so parameter semantics are trivially clear. The description adds context about the result set (received copies, ordering) that is not in the schema, which is useful. With no parameters, the baseline is 4.

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

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

The description clearly states the action ('List') and the specific resource ('notes that have been shared with the caller by someone else'), and distinguishes it from sibling tools like list_notes by specifying 'received copies' and sorting order. This is a specific verb+resource with scope that differentiates it.

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

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

The description implies when to use the tool (to see notes shared by others) but does not explicitly contrast it with alternatives like list_notes or search_notes. The context signals show sibling tool names, but the description itself lacks explicit guidance on when not to use it or when to prefer a sibling.

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?

With no annotations, the description carries the full burden, and it does disclose two meaningful traits: only 'active' notes and canvases are counted, and results are ordered most-used first. It says nothing about pagination, result caps, or how tags with zero active usage are handled.

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 resource and immediately qualifies it with scope and ordering. 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 zero-parameter read tool with an output schema covering the return shape, the description supplies the key semantics (what is counted, ordering). Only minor gaps remain around result limits or handling of unused tags.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 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 concrete resource (tags) plus the payload each entry carries (counts of active notes and canvases) and the sort order. This implicitly separates it from the sibling list_tags, which presumably returns tags without counts, though no sibling is named 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?

There is no statement of when to reach for this tool over list_tags, nor any exclusion or precondition. The use case (tag popularity/usage counts) must be inferred from the description alone.

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?

With no annotations provided, the description carries the transparency burden. It discloses the scope (active notes) and implies completeness ('every tag'), and being a list operation, no side effects are expected.

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 a single concise sentence, front-loaded with the action and clearly conveying the purpose 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?

For a simple list tool with no parameters and an output schema, the description adequately covers the action and scope. No further detail is necessary for an agent to use it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description properly avoids adding unnecessary parameter details since there are none.

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 specifies the action (list), the resource (tags), and the scope (caller's active notes). This distinguishes it from sibling tools, none of which mention tags.

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 context is clear: the tool is used to list tags from the caller's active notes. It doesn't explicitly mention alternatives or exclusions, but the scope is well-defined and siblings don't compete for this functionality.

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?

With no annotations, the description carries the full burden and delivers real value: it scopes search to 'active' notes, discloses that locked notes are only title-matched, and explains that this prevents leaking hidden body content. That security-relevant detail goes well beyond the schema. It does not cover result ordering, pagination, or what happens with empty/whitespace queries.

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 dense sentences, front-loaded with the core operation and then the two edge conditions (tag filtering, locked notes). No filler or restated field names.

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

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

The output schema exists, so return values need not be described, and the search scope/edge cases are handled well. However, for a 4-parameter tool with zero schema coverage, the description leaves `limit` and query semantics undefined, so an agent cannot fully reason about call behavior.

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 0%, so the description must compensate. It explains the semantics of `tags` and the `tag_match="all"` value, but `q` and especially `limit` (default 50, no max/pagination meaning) go entirely undocumented in both description and schema. Partial compensation only.

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

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

The description names a specific verb (full-text search) and resource (caller's active notes), and pins the searchable fields (titles and body text). This cleanly distinguishes it from siblings like list_notes or get_note, which are enumeration/lookup rather than search.

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 the optional narrowing condition ('only within notes carrying any of tags') which implies when the filter is useful, but it never explicitly says when to choose search_notes over list_notes, get_related_notes, or get_note_backlinks. Usage is left to inference rather than stated.

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