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

Annotations already indicate non-read-only, non-idempotent, non-destructive behavior; the description goes beyond them by disclosing the folder_name_conflict error and the fact that it lists existing folders. That is useful behavioral detail for an agent. No contradiction with annotations is present.

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, each serving a purpose: the action, the uniqueness constraint with error behavior, and the scope restriction. There is no filler, no repetition of the title, and the most important 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 low-complexity tool with one required parameter and annotations, the description covers the operation, the input constraint, the conflict failure mode, and the scope. There is no output schema and the success return value is not described, but that is a minor gap for such a simple create operation.

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 schema only says name is a string with minLength 1. The description adds that folder names must be unique and explains the conflict response, which is meaningful but still leaves out naming-rule details such as allowed characters, case sensitivity, or trimming behavior. The compensation is partial.

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

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

The description opens with 'Create a note folder in the local OpenWhispr app' – a specific verb and resource that clearly states the tool’s job. The final sentence, 'Creating a folder is the only folder change the bridge allows,' distinguishes it from any folder update or delete operation. This is unambiguous and separates it from the note-managing 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 lays out the unique-name requirement and the exact conflict return value, which tells an agent when the call can fail. It also makes clear that create is the only folder-mutation allowed. It does not explicitly direct agents to list_folders to pre-check names, but the guidance is still strong.

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

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

Annotations already mark this as a write, non-idempotent, non-destructive operation. The description adds valuable behavior beyond those flags: default-folder side effect, a notice field in the reply, note_type immutability, and the returned stored note. There is no contradiction with 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?

Three sentences, each earning its place: the operation, the folder default behavior, and the immutable note_type constraint. The main action is front-loaded, and there is 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?

With no output schema, it correctly states that the stored note is returned and points to the notice field for default-folder information. It covers the main decisions an agent needs; the remaining gap is the parameter semantics for source_file and note_type enum values, but they are minor for a creation 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 only 33%, so the description must compensate for some parameters. It does clarify folder_id behavior and note_type's immutability, but it leaves source_file and the practical meanings of the note_type enum values unexplained, creating a partial compensation.

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

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

The description opens with a specific verb and resource: 'Create a note in the local OpenWhispr app.' It also differentiates the tool from the update_note sibling by stating that note_type is fixed at creation and cannot be changed by update_note.

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

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

It gives practical context: omitting folder_id uses a default folder, the reply contains a notice field, and note_type must be chosen at creation because update_note cannot change it. There is no explicit 'use this instead of X' statement, but the create/update distinction is clear.

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

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

Discloses important behavior beyond the annotations: the operation has no confirmation/undo, and the API responds with 204 even if the note id did not exist, which is essential for the agent to set expectations.

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 brief, direct, and contains only necessary information. It front-loads the action and adds only high-value caveats.

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 delete operation, the description covers the action, the behavior on missing ids, and the lack of confirmation/undo. No output schema exists, so not describing return values is acceptable.

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 note_id is implicitly clear as the identifier of the note to delete, especially given the phrase 'whether the id existed.' The schema adds numeric constraints, but the description could explicitly state that note_id is the note's identifier.

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 the specific verb 'delete' and the resource 'note' in the context of the local OpenWhispr app, clearly distinguishing it from sibling tools like create_note, update_note, and get_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?

Provides critical usage guidance by warning that there is no confirmation step and no undo, and instructs the agent to confirm with the user before calling. It does not explicitly contrast with alternatives, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context beyond that: the transcript is omitted due to size, meeting notes expose transcript_segment_count plus a hint, and include_enhanced controls an alternative content version. This helps the agent understand what to expect from the response.

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

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

Three sentences with no filler: primary action is first, the important transcript caveat follows, and the optional parameter is explained last. 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?

For a read-by-id tool with no output schema, the description covers the returned fields, the transcript limitation, and the enhanced-content option. It is complete enough for an agent to call correctly, though it does not describe error behavior for nonexistent ids, which is a minor gap.

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

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

Schema coverage is 0%, but the description compensates by explaining that the note is fetched by id and that include_enhanced triggers the AI-cleaned version. It does not repeat exact types or defaults, but the schema itself documents those, so the description adds the missing semantic meaning.

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

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

The description opens with a specific verb and resource, 'Read one note by id', and lists the exact fields returned: title, folder, timestamps, content body. It clearly distinguishes itself from get_note_transcript by stating the transcript is never included.

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 makes clear this tool is for reading a single note by id and that the transcript is not included, pointing users toward get_note_transcript for that content. It does not explicitly contrast with list_notes or search_notes, but the by-id scoping is strong enough to imply those are for discovery rather than single-note 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 declare readOnlyHint=true, and the description adds substantial behavior beyond that: pagination semantics, relative timestamps, format-specific output shapes, speaker/source filters, and the important fact that a missing transcript returns an empty result rather than an error. This strongly supports correct invocation and interpretation.

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 compact, well-structured paragraph with no filler. It leads with the purpose, then enumerates the three formats and the key edge case. Every clause adds information an agent needs.

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

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

For a read-only tool with 7 parameters and no output schema, the description is sufficiently complete: it explains the main return formats, the pagination/filtering behavior, the long-recording recommendation, and the empty-result case. Parameter constraints are already covered by the schema, so nothing critical is missing.

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

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

The input schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema by explaining what each format produces, that speakers totals are intended as an initial summary, and that offset/limit apply to segment pages. This is a clear bonus over the schema.

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

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

The description states a specific verb and resource: 'Read a note's transcript.' It further explains the three output formats, making clear what the tool returns and distinguishing it from metadata-focused siblings like get_note. The purpose is not tautological and is immediately understandable.

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 contextual guidance, especially for format=speakers ('use it first on long recordings') and for the empty-result case. It does not explicitly compare against get_transcription or other siblings, but the intended usage is clear enough from the wording.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds useful behavioral context by naming what the response includes (full text, provider, model, status, error) and by clarifying that a dictation is not linked to a note. This goes beyond annotation-only knowledge without contradicting it.

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

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

Three short, information-dense sentences with no filler. The main action and returned fields are front-loaded, followed by the ID source and the sibling distinction.

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 tool with rich annotations and no output schema, the description covers the core action, return contents, ID provenance, and the primary alternative. Nothing essential for an agent to call it correctly is missing.

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

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

Schema coverage is 100%, and the schema already describes transcription_id as a dictation id from list_transcriptions. The description repeats that source but adds no extra parameter-level detail, so the schema is doing the heavy lifting; baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Read one dictation from the history by id') and enumerates the returned fields, making the tool's exact purpose clear. It also explicitly distinguishes this tool from get_note_transcript, so an agent can differentiate siblings without inspecting schemas.

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

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

It provides concrete guidance: IDs come from list_transcriptions, and if the user needs a note transcript, use get_note_transcript instead. This is explicit when-to-use and when-not-to-use guidance with a 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral details: counts come from a capped read, and the reply lists exactly what it cannot see. It also mentions that enabling transcript stats parses transcripts and can be slow on big meetings, adding performance transparency.

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 concise, two sentences, and front-loads the primary purpose. It avoids unnecessary detail while covering the core functionality, limits, and output nature efficiently.

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 (3 optional parameters, no output schema), the description sufficiently explains what the tool does, what inputs affect the outcome, and what the reply will contain, including the caveat about the capped read. It is complete enough for an agent to decide when and how to call 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?

The schema descriptions for notes_limit and include_transcript_stats are meaningful, explaining their effect on the results and performance. The main description adds context about the capped read. Although transcriptions_limit lacks an explicit schema description, its purpose is inferable from the overall context of the tool and its similarity to notes_limit.

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 summarises stored data in the OpenWhispr app, enumerating the types (notes, folders, transcriptions, dictionary words) and the dimensions (type, folder, month) along with word/character/audio totals. It distinguishes itself from sibling tools like list_notes and list_folders by focusing on aggregate counts rather than individual items.

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

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

The description implies the tool is for obtaining summary statistics, and the sibling tools list individual entities, so the intended use is inferable. However, it does not explicitly name alternatives or provide explicit 'use this when' or 'use that when' guidance, leaving the choice to the reader.

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 declare readOnlyHint=true, and the description reinforces a read-only health check without side effects. It adds value beyond the annotations by revealing the dynamic nature of the bridge (port and token change on restart) and enumerating the returned fields (host, port, handshake path, app version). It doesn't describe the exact failure response of the tool itself, but the trigger errors imply that 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?

The description is two sentences with no filler. The first sentence states purpose and output; the second delivers usage guidance. It is front-loaded and 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?

There is no output schema, so the description carries the burden of explaining return values; it does so by listing host, port, handshake file path, and app version. It also covers the main usage trigger. It does not specify the response format or behavior when the app is not running, but for a simple read-only health check the description is sufficiently complete for an agent to invoke and use 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?

The tool has zero parameters and the schema coverage is 100%, so the input surface is fully documented by the schema. With no parameters to explain, the description is not required to compensate, and the baseline of 4 is appropriate.

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

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

The description uses a specific verb ('Check') and identifies a distinct resource ('the local OpenWhispr app... its CLI bridge'), then lists the returned data. This clearly distinguishes it from sibling tools that operate on notes, folders, transcriptions, dictionary, and usage.

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

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

It explicitly states when to call the tool: 'Call this first when another tool fails with bridge_not_running, bridge_unreachable or unauthorized.' It also adds crucial context that the port and token change on every app restart, making the guidance actionable and unambiguous.

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, so the safe-read behavior is covered. The description adds meaningful context beyond annotations: it identifies the dictionary as local to the OpenWhispr app and discloses that the return value includes both the words and the shape in which they were stored. This adds helpful behavioral detail without contradicting 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?

The description is two sentences, with the core action and resource front-loaded. The second sentence adds the return-value shape without redundancy. Every part earns its place 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 no parameters, no output schema, and read-only annotations already provided, the description covers what the tool does and what it returns. An agent has enough context to select and invoke this tool correctly without further elaboration.

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 there is nothing for the description to elaborate on. The baseline for no parameters is 4, and the description appropriately focuses on the output semantics rather than inventing parameter guidance.

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 ('List') and a specific resource ('the custom dictionary of the local OpenWhispr app'), and clarifies the purpose: it shows words the transcriber is told to spell a particular way. This clearly distinguishes it from sibling tools such as update_dictionary and list_notes.

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 makes the read-only listing purpose clear, and the sibling context includes update_dictionary as the obvious write counterpart. However, it does not explicitly say 'use this when you need to view the dictionary' or mention any alternative or exclusion, so usage guidance remains mostly 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?

Annotations already declare readOnlyHint=true, and the description enriches this by disclosing that 'the bridge returns every folder at once — there is no limit and no paging here.' This adds behavioral detail beyond the annotations, such as the non-paginated, complete-result 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?

Three sentences with no wasted words. It front-loads the core purpose, then states the practical use case, then the key behavioral caveat. Every sentence adds value.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description is complete: it names the resource, the returned fields, the use case, and the non-paginated behavior. Nothing essential is missing for an agent to invoke 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 input schema has zero parameters, so the baseline is 4. The description appropriately focuses on the returned fields instead of parameters, adding useful context about what the agent will receive.

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 ('List'), a specific resource ('the note folders of the local OpenWhispr app'), and the exact data returned ('ids, names and default flags'). It clearly differentiates itself from sibling tools like list_notes and create_folder by naming the resource and its downstream purpose.

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

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

The description explicitly tells the agent when to use this tool: 'Use it to find the folder_id that list_notes, create_note and update_note take.' It provides clear context for invocation, though it does not state explicit exclusions or alternatives for cases where this tool should not be used.

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 report readOnlyHint=true, but the description adds meaningful behavioral detail beyond that: pages are served from a single snapshot, the cursor must be passed verbatim with unchanged filters, and a stale cursor fails with snapshot_expired requiring a fresh list without a cursor. This gives the agent important failure-mode knowledge not available from annotations or 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?

Four sentences with no wasted words, key information front-loaded: action, ordering, filters, then return-content limits, then pagination protocol and failure mode. Every sentence adds operational guidance.

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 listing tool with no output schema, the description covers the critical operational context: what is returned, in what order, how paging works, and what happens when a cursor is stale. The only minor absence is an exact list of summary fields, but the term 'summaries' plus the explicit exclusion of body/transcript is sufficient for correct use.

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 note_type and folder_id as filters, and cursor semantics as snapshot-based pagination. However, it does not describe page_size, though schema constraints (default 20, maximum 100) make the parameter mostly self-evident and the omission is a minor gap rather than a fatal one.

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 action ('List notes'), the ordering ('newest first'), and the supported filters ('note_type and/or folder_id'). It also explicitly distinguishes itself from note-content tools by noting it returns 'summaries only — no note body, no transcript', which differentiates it from get_note and get_note_transcript without ambiguity.

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?

Provides clear context for when this tool is appropriate: when listing summaries filtered by note_type and/or folder_id, and when paginating with a snapshot cursor. It implies that body/transcript retrieval belongs elsewhere ('no note body, no transcript'), though it does not explicitly name get_note or search_notes as alternatives, stopping just short of a fully explicit routing guide.

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

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

The readOnlyHint annotation already establishes safety, and the description adds useful behavioral context beyond that: results are newest-first, rows cannot be linked to notes, and discarded/deleted items are omitted. There is no contradiction with 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?

Three compact sentences each earn their place: the first states action, scope, and output fields; the second disambiguates from related tools; the third discloses an important limitation. No redundant or filler content.

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 read-only list operation with no output schema, the description covers ordering, returned fields, exclusive scope, exclusions, and the relevant alternative tool. The structured schema handles parameter details, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema fully documents both limit and status. The description adds only contextual framing like 'newest first' rather than new parameter-level meaning, which matches the baseline of 3 for high schema coverage.

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 begins with a specific verb and resource: 'List the OpenWhispr dictation history (newest first)' and enumerates the returned fields. It explicitly differentiates itself from note transcripts and names the sibling get_note_transcript, leaving no ambiguity about what this tool returns.

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 exactly when to use this tool versus an alternative: 'These rows are NOT note transcripts... use get_note_transcript for those.' It also clarifies scope by noting discarded and deleted dictations are invisible, which helps an agent interpret results correctly.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: FTS5 prefix AND matching, every word being required, no relevance ranking, and the exact return shape (summaries with matched_in and a snippet). This gives the agent strong expectations for invocation and response handling.

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 compact, front-loaded with the core function, and every sentence adds distinct value: behavior, limitations, return format, and routing to alternatives. 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?

Given the simple two-parameter schema, read-only annotation, and lack of an output schema, the description sufficiently covers what an agent needs: query semantics, result content, and guidance on sibling tools. Nothing essential is missing.

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

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

The schema is minimal and has 0% description coverage, so the description carries the burden for parameter meaning. It richly explains the q parameter's prefix AND semantics. The limit parameter is not elaborated, though its schema default and range are already visible.

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

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

The description states a specific verb and resource: full-text search over note titles, bodies, and AI-enhanced text. It also clearly differentiates this tool from siblings by specifying what it returns and what it does not do (no semantic search, no relevance score).

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

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

The description explicitly tells the agent when to use alternatives: 'use list_notes to browse and get_note for a full body.' It also clarifies the search semantics, so an agent can decide whether this tool fits the need versus semantic or browsing 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?

The description adds meaningful behavior beyond the annotations: words are trimmed and de-duplicated, case is significant, and the tool returns both the sent payload and the resulting dictionary. These details help the agent predict side effects and interpret the response, especially since no output schema is present.

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 three sentences with no filler. It front-loads the primary action, then adds essential processing semantics, and finally describes the return value in a natural order. Every sentence contributes useful information.

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

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

Given a simple two-optional-parameter tool, no output schema, and annotations covering read-only, destructiveness, and idempotency, the description provides what an agent needs: purpose, parameter behavior, processing rules, and return shape. It is complete for correct invocation in this context.

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 no descriptions and names only 'add' and 'remove', so the description must compensate. It does so by explaining the intended function of both arrays and by adding important value semantics like trimming, de-duplication, and case sensitivity. It could go further, for example by describing behavior when the same word appears in both arrays, but for simple string arrays the current coverage is strong.

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

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

The description opens with a specific action ('Add or remove words') and names the exact resource ('the custom dictionary of the local OpenWhispr app'). This clearly distinguishes it from sibling tools, especially list_dictionary, and leaves no ambiguity about what the tool does.

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 makes its core use case clear: modify the custom dictionary by adding or removing words. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention read-only alternatives like list_dictionary for inspection-only use. The usage context is implied rather than explicitly guided.

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

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

Beyond the annotations (which already indicate idempotent and non-destructive), the description reveals a subtle behavior: rewriting content leaves existing enhanced_content in place and the app continues to treat it as current, with the reply warning about this. This is exactly the kind of behavioral nuance that annotations cannot express and prevents the agent from assuming content changes also regenerate enhanced_content.

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 tight, front-loaded with the core action, and each sentence carries distinct value: the first names the operation, the second sets boundaries, the third clarifies a critical side effect. There is no repetitive or filler wording.

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 has a non-trivial semantic quirk around enhanced_content and non-writable fields, and the description captures it well. It informs the agent what can be changed, what cannot, and what happens after a content rewrite, which is sufficient context for correct invocation even without an output schema.

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 only 25% schema description coverage, the description compensates meaningfully: it identifies title, content, and folder as the writable parameters, and explains a consequence of content rewriting. It also clarifies non-writable fields even though they are not in the schema, which helps the agent avoid offering unsupported updates. It does not elaborate on note_id, but that parameter is self-evidentifying and required.

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

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

The description opens with a specific verb and resource: 'Change a note's title, content or folder in the local OpenWhispr app.' It clearly scopes the operation to update actions on notes and names the exact editable fields, making it unmistakable from sibling tools like create_note, delete_note, or update_dictionary.

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 usage context: use this tool when you need to change a note's title, content, or folder. It also explicitly states when not to use it by listing note_type, transcript, and enhanced_content as deliberately non-writable, though it does not point to alternative tools by name or provide broader conditionals.

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