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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the claim that it 'Returns the exact total', useful versus an estimated count but thin; no pagination, auth, or scoping caveats are given.

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

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

Two sentences, zero waste, with the core action front-loaded and the optional filtering qualifier placed after it. Nothing redundant or 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?

With an output schema present and 100% schema coverage plus full annotations, the description need not cover return values or safety. It is nearly complete, missing only sibling differentiation among the several count_* 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 100%, so the baseline is 3. The description restates the period values already enumerated in the schema and does not explain the precedence rule (from/to overriding period) that the schema itself encodes, adding no meaning beyond it.

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 clear verb+resource ('Count how many insights (notes)') and names the scope options. However, it never distinguishes itself from sibling counters like count_literature_notes or count_drafts, so an agent must infer which counter applies to which note type.

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?

Implies usage through the optional date-range/period framing, but gives no explicit when-to-use or when-not-to-use guidance, nor any routing to alternative tools such as list_recent_notes or count_literature_notes. Adequate but with a clear gap.

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

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

Annotations already declare 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds one genuinely useful behavioral fact — that it returns the full text rather than a summary — but says nothing about error behavior for a bad id or whether the note body can be large.

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 resource and access mode first and no filler. Every word 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?

Annotations cover the safety profile and an output schema exists, so return values need not be explained. Calling it correctly requires only the id, which is documented; the only missing nuance is guidance for an unknown or foreign id, a minor gap for a single-param getter.

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?

One parameter with 100% schema coverage, so the schema already documents 'id'. The description adds only that the id refers to a literature note specifically (not a generic note), which is a small but real disambiguation 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?

The description gives a specific verb (fetch) and resource (literature note) plus the mode of access (by id) and result (full text). It implicitly separates this from the list/search literature note siblings, but never names them, so an agent must infer the boundary itself.

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' implies the precondition that the caller already holds a note id, which rules out discovery-style use. However, no alternatives are named (e.g. search_literature_notes or list_recent_literature_notes for when no id is known), so routing guidance 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — no note on authorization, whether a missing id errors or returns empty, or retrieval side effects.

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, and the parenthetical listing of supported media types adds useful scope without waste.

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 (one required param), annotations cover its read-only/idempotent nature, and an output schema exists so return values need not be described. The only shortfall is the absence of routing guidance relative to the many sibling lookup and search 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 100% with a single self-documenting parameter ('The media item's id'). The description's 'by id' only restates the schema, adding no format, prefix, or validation detail, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a single media item) with the lookup key (by id), and enumerates the resource types (book, article, podcast). It is clear what the tool does, though it never names the sibling tools (search_media, list_recent_media) it must be distinguished from, leaving differentiation 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 phrase 'by id' implies the tool is for direct lookups when an id is already known, which is usable guidance. However, it never states when to prefer this over search_media or list_recent_media, nor any exclusions, 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that the payload includes full text plus tags, but says nothing about failure behavior for an unknown id or access constraints. Since an output schema exists, deeper return-value prose is unnecessary.

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, no filler, front-loaded with the verb and the resource. Nothing could be removed without losing meaning.

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

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

For a single-parameter, read-only lookup with full schema coverage, rich annotations and a declared output schema, the description is sufficient to call the tool correctly. Only a brief note on what id values are valid would make it airtight.

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 schema does the documentation work. The phrase "by id" adds no format, provenance or validation detail beyond what the schema already states ("The note's id"). 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"), a specific resource ("one of the user's insights (notes)") and scope ("full text and tags"), keyed by id. The resource naming implicitly separates it from get_draft, get_literature_note and get_media, though it never explicitly contrasts itself with those siblings.

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

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

Usage is only implied: fetch a single note by id versus discovering notes via list_recent_notes or search_notes. There is no explicit when-to-use statement, no precondition (e.g. id must come from a prior search), and no 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?

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the 50-item hard cap and the recency-based ordering. Those are genuinely useful behavioral facts beyond the structured fields, though the default limit of 10 is left to the schema.

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

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

Two sentences, zero filler, with the core operation front-loaded and the anti-pattern caveat immediately after. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation. For a single-optional-parameter read tool, the description covers scope, ordering, cap, and the counting caveat — nothing an agent needs to select or invoke it correctly is missing.

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

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

Only one optional parameter with 100% schema description coverage ('default 10, max 50'), so the schema already carries the semantics. The description's mention of the 50-item ceiling overlaps the schema's constraint rather than adding new meaning; 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 + resource + scope: 'List the user's most recently created literature notes.' The 'most recently created' ordering distinguishes it from search_literature_notes, and the resource ('literature notes') distinguishes it from list_recent_notes/drafts/media.

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 rules out a misuse case: 'Not for counting ... it cannot tell how many the user has,' which routes the agent toward count_literature_notes. It stops short of naming that sibling tool directly, so the exclusion is clear but the alternative 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed world, so the safety profile is fully covered. The description adds only the 'most recently added' ordering signal and the media-type scope, with no detail on how 'recent' is defined or how ordering/paging behaves. Modest added value on top of 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?

One compact sentence with no filler, front-loading the verb, resource, and recency constraint. Nothing to trim.

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, has a documented parameter, complete annotations, and an output schema, so return format need not be explained. Remaining gaps are minor: how 'recent' is defined and whether results are truncated without paging, neither of which is likely to cause a wrong 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 description coverage is 100% and the single limit parameter already documents default 10 and max 50. The description adds nothing about limit or the result ordering it controls, so the schema does the heavy lifting and the baseline 3 applies.

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

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

States a specific verb (List), resource (media), and scope (most recently added), with concrete content examples (books, articles, podcasts). It implicitly separates itself from get_media (single item) and search_media (query-based) through the 'recently added' framing, but never names a sibling explicitly, so it stops short of a 5.

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

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

No when-to-use guidance and no alternatives named. An agent must infer that list_recent_media is the right pick over search_media when no query is available, and nothing states exclusions or prerequisites. Only the resource name implies usage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a meaningful behavioral trait: results are truncated at 50 and the call therefore cannot serve as a count, which is a caveat 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?

Two short sentences with no filler; the purpose is front-loaded and the disqualifying condition follows immediately. Every clause earns its place.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. Purpose, scope, and the counting exclusion are all present; ordering semantics for 'recent' are the only minor omission, and the tool name and title make that self-evident.

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?

Single parameter with 100% schema description coverage; the schema already documents limit, its default of 10 and its max of 50. The description adds no syntax or interpretation beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the user's most recently created insights (notes)') and disambiguates from the count_* family with the explicit 'Not for counting' clause. It does not explicitly contrast with search_notes, but the counted-vs-listed distinction against siblings is clear.

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

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

Gives an explicit when-not ('Not for counting') with the rationale (50-note cap means it cannot report totals), which routes the agent away from count_notes. It lacks an explicit pointer to the alternative for filtered retrieval (search_notes) or for other note types.

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 read-only, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: matching is lexical rather than semantic, and empty results should prompt reformulation rather than telling the agent the data is absent.

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

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

Three tight sentences, each doing distinct work: what is searched, how matching behaves, and how to narrow to a single media item. The scope constraint is front-loaded and there is no filler.

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

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

With an output schema present, return values need not be explained. For a zero-required-parameter, two-param search tool, the description supplies everything an agent needs: search domain, matching semantics, and the media_id routing path.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: query searches only the note body (not the media title/author), and media_id is the id of the underlying book/article/podcast. It also clarifies the query-optional interaction with media_id, which aids correct invocation.

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

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

States a specific verb and resource ('Search the user's literature notes') and immediately bounds the search scope to note text rather than title or author. That scoping detail distinguishes it from siblings like search_notes, search_media and search_drafts without requiring the agent to open 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?

Gives concrete guidance: keyword search is literal, so retry with different wording if nothing is found, and pass media_id to retrieve all notes on one book/article/podcast. It does not explicitly name sibling alternatives (e.g. use search_notes for non-literature notes), so it stops just short of full when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so safety is fully covered. The description adds one genuinely useful behavioral fact beyond that, that each result carries the item id (enabling chaining to get_media), but says nothing about match semantics (substring vs fuzzy), result caps, 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 short sentences, zero filler, with the core purpose front-loaded and the result-shape detail trailing. Nothing needs trimming.

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 needn't be explained, and with one well-documented parameter the definition is nearly sufficient. Only match semantics and result limits are left unspecified, which is a minor gap for a simple search 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?

With a single parameter and 100% schema description coverage, the schema already documents 'query' fully; the description's 'by title or author' essentially restates it. Baseline 3 is appropriate with no additional syntax or format detail supplied.

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) and resource (the user's media), and narrows the match fields to title or author, which separates it from list_recent_media and get_media. It stops short of explicitly naming or contrasting those siblings, but the intent is 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?

Usage is only implied: 'by title or author' suggests a keyword-lookup tool rather than an id lookup (get_media) or a recency browse (list_recent_media), and mentioning that results carry the id hints at a follow-up get_media call. There is no explicit when-to-use statement or exclusion, so an agent must infer the routing.

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

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 genuinely useful behavioral trait beyond them: matching is literal keyword matching, not semantic, which predicts false negatives and shapes retry behavior.

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

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

Two short sentences, zero filler, and the positive scope is front-loaded before the matching caveat and the exclusion list. Every clause carries load.

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, the description covers scope, matching behavior, failure recovery and exclusions; return values are covered by the output schema and safety by annotations. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single required parameter, so the schema already documents 'query' as a keyword or tag. The description's 'by keyword or tag' restates that without adding syntax, matching rules, or examples, 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?

Specific verb (search) plus a precisely scoped resource (the user's own insights / notes written in their own words), and it explicitly carves out what it is not for (books, articles, podcasts, and notes on them). That exclusion set lets an agent distinguish it from search_literature_notes and search_media 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 a clear usage context and a concrete recovery heuristic ('try another wording if nothing is found'), plus an explicit when-not list. It stops short of naming the alternative sibling tools (search_literature_notes, search_media) by name, so routing relies on the agent mapping content types to those siblings itself.

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