ThinkerNotes

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds little beyond annotations: it notes the count reflects drafts the user has 'added' and returns an 'exact total', but discloses no rate limits, auth needs, or edge-case behavior.

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

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

Two tight sentences with the core action front-loaded and the filtering caveat immediately after; every clause earns its place with no filler.

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

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

An output schema exists, so return values need not be explained (the brief 'exact total' note suffices), and annotations cover the safety profile. The only residual gap is the absence of sibling routing guidance, which is minor for a simple counting 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 the schema already documents to, from, and period with their override semantics. The description loosely echoes the period options ('this week, this month, this year, or all time') but adds no syntax or precedence detail beyond what the schema provides.

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 (count) and a specific resource (inbox drafts the user has added), which inherently distinguishes it from count_notes and count_literature_notes siblings. It stops short of explicitly naming those alternatives, so it is clear but not fully differentiated in prose.

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

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

The description explains the optional filtering behavior (date range or period), which implies how to scope the count. However, it gives no guidance on when to use count_drafts versus count_notes, list_recent_drafts, or search_drafts, and names no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the safety profile is fully covered. The description adds that it 'Returns the exact total' (as opposed to an estimate), which is useful context, but it says nothing about authorization, empty results, or error behavior. With annotations carrying the main burden, this is adequate but thin.

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

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

One sentence, front-loaded with the verb and resource, with the optional filtering mentioned second. The parenthetical resource definition earns its place; slightly long but no wasted clauses.

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-required-parameter, read-only count tool with an output schema, the description covers the resource, the optional filters, and the nature of the return value. Nothing essential for correct invocation is missing, though alternatives are not addressed.

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%, including the note that 'to'/'from' override 'period' and that period defaults to all_time. The description adds nothing beyond the schema's parameter documentation, so the baseline 3 applies when the schema does all the work.

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

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

The description states a specific verb (count) and resource (literature notes) and even disambiguates the resource as 'notes taken on books, articles and podcasts', which separates it from the generic count_notes sibling. However, it never explicitly names or contrasts with the sibling tools, so differentiation is inferred rather than stated.

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

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

The description explains the filtering options ('optionally within a date range or period like this week, this month, this year, or all time'), which implies when to supply each parameter. It gives no guidance on when to choose this tool over count_notes or count_drafts, nor any prerequisites, so usage 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?

The description adds behavioral context by stating which entities are included ('ones in a collection') and explicitly listing the valid period formats (e.g., 'this week,' 'this month,' 'all time'), providing constraints beyond the schema or annotations.

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

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

The description is extremely concise, achieving its goal in a single, well-structured paragraph. Every sentence is functional, starting with the core action and ending with the guaranteed output.

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 low complexity of the function (a singular count), the description is highly complete. It covers scope, filtration mechanisms, and the precise nature of the return value, leaving no functional questions unanswered for the agent.

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?

Since schema coverage is 100%, the description adds crucial semantic value by clarifying that filtering is optional and detailing the purpose of the date/period parameters—to count within a specific temporal 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 clearly defines the purpose as counting notes while distinguishing it from drafts, which immediately helps differentiate it from similar sibling 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?

It establishes clear boundaries regarding what is counted (user notes, included in collections) and what is excluded (draft notes). While it doesn't explicitly name alternatives, it defines its scope well enough for usage 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?

The annotations already declare the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description carries a lighter burden. It adds nothing beyond that, however: no statement about behavior when the id is unknown, whether the lookup is scoped to the caller's library, or any access constraint.

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

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

One short sentence, front-loaded with the verb and resource, with the parenthetical clarifying the resource type. There is no filler and nothing is buried.

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 an output schema present and rich annotations, the description need not explain return values or safety. For a single-parameter read of this simplicity it is nearly complete, though a brief note on sourcing the id or on not-found behavior would close the remaining gap.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the baseline is 3. The description's 'by id' adds no format, source, or provenance information (e.g., where to obtain a collection id) beyond what the schema already states.

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 ('Fetch') and resource ('a single collection') and even clarifies the domain of 'collection' (a book, article or podcast), which an agent could not infer from the name alone. The 'by id' phrasing implicitly separates it from list_recent_collections and search_collections, though those siblings are never named.

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 agent must infer that this tool is appropriate when it already has a collection id, and that search_collections or list_recent_collections should be used otherwise. No explicit when-to-use or when-not-to-use 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description usefully clarifies that the full text (not a summary) is returned, but says nothing about error behavior for a missing id or permission requirements.

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

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

One compact sentence that front-loads the verb and resource with no filler. Every clause (full text, user's inbox, by id) carries distinguishing 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 an output schema present, the definition needn't describe return values, and the parameter schema is fully documented. The only remaining gap is guidance on id sourcing and failure modes, which is minor given the tool's simplicity.

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

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

Schema coverage is 100% and the single parameter is documented as "The draft's id". The description reinforces the notion of a per-user inbox draft, but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (fetch) and resource (full text of an inbox draft) plus the access pattern (by id), which cleanly separates it from list_recent_drafts, search_drafts, and count_drafts. It does not name those siblings explicitly, so it falls 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?

"By id" implicitly tells the agent this is the retrieval path once an id is known, and "the user's inbox drafts" scopes it to a specific collection. There is no explicit when-to-use-vs-search/list guidance or statement of what happens if the id is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds two useful facts beyond that: the note belongs to the user (ownership scoping) and the result is the full text rather than metadata. It says nothing about error behavior for a missing id, but the safety and return-shape burden is largely carried elsewhere.

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

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

One sentence, front-loaded with the verb and resource, with no redundant restatement of the title or annotations. Every clause ('full text', 'one of the user's', 'by id') 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?

With one required parameter, full schema coverage, a present output schema, and rich annotations, the definition covers what an agent needs to invoke it correctly. The only residual gap is the absence of any statement about failure when the id does not exist.

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

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

Schema coverage is 100% and there is a single required 'id' parameter already documented in the schema, so the baseline is 3. The description's phrase 'by id' confirms the id identifies a specific note but adds no format, source, or provenance detail beyond the schema.

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

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

States a specific verb+resource pair ('Fetch the full text of ... literature notes') and scopes it to a single note identified by id, which implicitly distinguishes it from list_recent_literature_notes and search_literature_notes. It stops short of naming those siblings explicitly, so an agent must infer the boundary from 'by id'.

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 rather than stated: the 'by id' phrasing signals this is the retrieval step once an id is known, and the sibling names (list_/search_/count_literature_notes) make the alternative paths inferable. There is no explicit when-to-use or when-not guidance, and no note about what happens if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds the concrete return contents (full text, tags, source), but since an output schema exists this is modest additional value rather than essential disclosure.

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

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

A single front-loaded sentence with the verb first and zero filler. It is appropriately sized for a one-parameter lookup 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?

For a simple single-parameter read with full annotation coverage and an output schema, the description supplies enough to call correctly. The only mild omission is guidance for when the id is not known, which sibling search/list tools would cover.

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 there is a single required 'id' parameter already documented. The description only restates that a note is looked up 'by id' and adds no format, source, or lookup semantics 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?

States a specific verb (Fetch) and resource (one of the user's notes) plus the scope of what is returned (full text, tags and source). It implicitly distinguishes notes from the sibling note-type tools (get_draft, get_literature_note) by specifying 'notes', though it does not name those alternatives 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 'by id' — fetch a single note when you already have its identifier — but there is no explicit when-to-use guidance, exclusions, or pointers to search_notes/list_recent_notes as alternatives for when the id is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false and closed-world scope, so the safety profile is covered. The description adds only the clarification of what content types a collection contains; it says nothing about recency window, ordering, or truncation behavior that an agent might need beyond the annotations.

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

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

A single front-loaded sentence with no filler; the parenthetical content-type list is short and genuinely disambiguating. It is efficient, though it leaves no room for scoping detail.

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, the parameter is fully documented, and an output schema exists, so return format needn't be described. Still, an agent gets no hint about the recency window, ordering, or how results relate to search_collections, which is a modest gap for a list 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?

Only one optional parameter, and the schema documents it fully (default 10, max 50) at 100% coverage, so the schema does the heavy lifting. The description adds no meaning about limit, so baseline 3 applies.

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

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

States a specific verb and resource ('List the user's most recently added collections') and clarifies what a collection holds (books, articles, podcasts). This separates it from get_collection and search_collections, though it never names those siblings 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?

The word 'recent' implies a browsing/recency use case rather than a lookup, which implicitly contrasts with search_collections and get_collection, but no explicit when-to-use or when-not-to-use guidance is given and no sibling is named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds a real behavioral trait beyond them: a hard 50-draft ceiling that makes it unusable as a counting source. It does not add pagination or ordering-detail context, so it falls short of the top band.

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 with zero filler; the purpose leads and the caveat follows immediately. Every sentence carries information an agent needs.

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

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

With an output schema present, return values need no explanation, and the description supplies purpose, exclusion, and the item cap. It is close to complete for a one-optional-param list tool, missing only ordering details that the output schema likely covers.

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 single parameter is fully documented in the schema (coverage 100%, default 10 / max 50), which sets the baseline at 3. The description restates the 50 cap but adds no syntax, range behavior, or interaction detail for 'limit' beyond the schema text.

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

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

States a specific verb (List) plus resource and scope (most recently created inbox drafts), which separates it from search_drafts and list_recent_notes without opening either schema. The scoping adjective 'recently created' is meaningful and front-loaded.

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

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

Explicitly gives a when-not condition ('Not for counting ... cannot tell how many the user has') with the reason, which cleanly routes the agent away from count_drafts. It stops short of naming count_drafts as the alternative tool or addressing search_drafts for filtered retrieval.

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 establish readOnly/idempotent/non-destructive, so the description only needs to add behavior beyond that. It does add real value by disclosing the 50-note cap and the resulting inability to count, which is the kind of truncation detail the annotations do not cover. Pagination beyond the cap is not addressed, keeping 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 short sentences, zero padding, with the capability first and the exclusion second. Every sentence earns its place.

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

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

With an output schema present, return shape need not be explained, and annotations cover the safety profile, so the description only has to convey scope and limits, which it does. A brief note on what happens past the 50-note cap would make it 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 description coverage is 100% and the single 'limit' parameter is fully documented with its default and max in the schema. The description mentions the 50 ceiling but adds no format or interaction detail beyond what the schema already states, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('List the user's most recently created literature notes') and implicitly conveys ordering by recency. It differentiates against the count_* siblings but says nothing about how it differs from search_literature_notes, the other plausible 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?

It gives an explicit when-not ('Not for counting') plus the reason (returns at most 50), which directly routes the agent to count_literature_notes. It stops short of naming search_literature_notes as the alternative when the user wants a filtered or exhaustive lookup.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuine behavioral limit — a hard cap of 50 results and the consequence that it cannot answer counting questions — which is context an agent needs to interpret results correctly. It omits any mention of result ordering semantics beyond 'most recently created' or what happens when the cap truncates.

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, both earning their place: the first defines scope, the second defines the exclusion. The core capability is front-loaded and there is no redundant framing.

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?

Return values are covered by an existing output schema, safety by annotations, and the sole parameter by a fully-described schema, so the description needn't do more. The only looseness is the slightly ambiguous phrase 'including the ones in a collection', which doesn't state whether that means cross-collection aggregation is automatic or requires a filter the tool doesn't accept.

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

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

With a single parameter at 100% schema description coverage (default 10, max 50), the schema already carries the semantics. The description's 'at most 50 notes' restates the schema's max rather than adding new meaning about the limit parameter or its interaction with the collection 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 gives a specific verb and resource ('List the user's most recently created notes') plus a scope detail about included collections, which lets an agent distinguish this from the sibling count_* tools. It does not explicitly separate itself from list_recent_drafts or list_recent_literature_notes, relying on the resource name 'notes' to do that work.

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 an explicit when-not condition with reasoning ('Not for counting... it cannot tell how many the user has'), which directly routes the agent away from count_notes. It never names the alternative tool by name, and gives no guidance on when to prefer search_notes over this recent-list 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one useful behavioral fact — that each result carries the item's id, which enables chaining into get_collection — but says nothing about matching semantics, result limits, or ordering.

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

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

Two tight sentences with the action and scope front-loaded and the result-shape note second. No filler or 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 one-parameter read tool with an output schema, the description is nearly complete — return values need not be explained and the mention of the id field is a helpful bridge to get_collection. The only remaining gap is matching behavior and any result cap, which an agent might reasonably want before issuing the call.

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

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

Schema coverage is 100% and the single 'query' property is already documented as 'Title or author to search for'. The description restates that same meaning ('by title or author') without adding format, case-sensitivity, or matching rules, so the schema does the work here.

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 and resource ('Search the user's collections') and narrows the search surface to title or author, with concrete examples of what a collection holds (books, articles, podcasts). This separates it from get_collection and list_recent_collections, though it never names those siblings 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: call this when you have a title or author string rather than an id. There is no explicit statement of when to prefer get_collection (known id) or list_recent_collections (browsing by recency), nor any guidance on partial-match expectations or empty-result handling.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the description only needs to add what they don't cover. It does add a meaningful trait — matching is literal word matching, not semantic — plus a fallback strategy, though it stays silent on case sensitivity, which fields (subject vs body) are searched, and result limits.

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

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

Two short sentences, zero filler. The purpose is front-loaded and the caveat about literal matching follows immediately after, so an agent can decide in one read.

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 an output schema present, return values need not be described, and full annotations cover the safety profile. For a one-parameter search tool this is nearly complete; only ordering/pagination behavior for the result set is left unaddressed.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains 'query'. The description adds no syntax detail beyond it — nothing about multi-word queries, phrase quoting, or operator support — so the baseline of 3 is appropriate.

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

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

States a specific verb (Search) plus resource and scope (the user's inbox drafts) in the first clause, which cleanly separates it from list_recent_drafts, get_draft, and count_drafts. The keyword-vs-meaning sentence further pins down the retrieval semantics of this tool versus its similarly named siblings.

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

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

The description tells the agent what to do when results are empty ('try another wording'), which is a useful operational hint, but it never states when to prefer this search over list_recent_drafts or get_draft. Usage is implied by the verb rather than explicitly scoped against alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the key added value is the matching semantics: literal word matching rather than meaning-based search, restricted to note text. That is genuinely useful behavioral context an agent would otherwise have to discover empirically. Pagination and result-size behavior are not covered, but an output schema 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?

Three sentences, each front-loaded with the constraint that matters most: what is searched, how matching works, and the alternate retrieval path. No repetition of the schema and 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 two-optional-parameter read tool with an output schema and full annotation coverage, the description supplies what is needed to call it correctly. The one gap is what happens when both parameters are omitted, which the description never addresses.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining that collection_id corresponds to 'one specific book, article or podcast', clarifying that a collection is the source work rather than an arbitrary grouping. The 'leave it out to list every note' behavior is documented only in the schema, not the 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?

States a specific verb and resource ('Search the user's literature notes') and immediately scopes the search domain: keyword matching in note text, explicitly 'not the title or author of the book'. It also names a distinct access pattern (fetch by collection_id), so an agent can tell it apart from list_recent_literature_notes or get_literature_note.

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

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

Gives clear when-to-use guidance: keyword search over note text, with the explicit fallback 'try another wording if nothing is found' and a route to single-work retrieval via collection_id. It does not name or exclude any sibling tool by name, so the agent must infer the boundary against list_recent_literature_notes and get_literature_note.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: matching is lexical rather than semantic, so a miss may be a wording problem rather than an absence, and collection-contained notes are in scope. Result limits and ordering are left to the output schema.

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

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

Three short sentences: capability and scope first, then matching semantics, then exclusions. No filler, and the most decision-relevant information is front-loaded.

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

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

For a one-parameter read-only search with an output schema present, the definition covers what to search, what is included, how matching works, and what to exclude. Missing only result-set behavior such as limits or ordering, which the output schema plausibly covers, so the residual gap is minor.

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

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

Schema coverage is 100% and the single parameter is already documented as "Keyword or tag to search for". The description restates that and adds only the clarification that the term is matched against text words rather than meaning. Baseline 3 applies since the schema carries the parameter definition.

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 ("Search the user's notes") plus the matching dimension ("by keyword or tag"), and explicitly delimits scope: collection notes are included, while literature notes and drafts are not. An agent can separate it from search_literature_notes, search_drafts and search_collections without opening any schema.

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

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

Negative guidance is explicit and routes to the correct siblings: not for books/articles/podcasts themselves, and not for drafts. It also gives a recovery instruction ("try another wording if nothing is found"). It stops short of naming the alternative tools outright, so routing still requires a small inference.

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