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

With no annotations present, the description carries the full burden and does disclose the key side effect: it writes a Markdown report (with a listening checklist) and returns only a summary. That non-obvious write-then-summarize behavior is exactly what an agent needs. It does not say where the report file lands or whether it overwrites prior reports.

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

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

Front-loaded summary sentence followed by a compact Args block that maps one-to-one to the parameters. No filler; the only structural quibble is that the report-writing behavior sits in the second line rather than being grouped with the summary.

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

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

No output schema exists, and the description does state the return surface ('returns the summary') plus the artifact produced, which is the critical gap covered. Remaining omissions—report output path and handling of the samples cap—are modest for a zero-required-parameter reporting tool.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it defines 'since'/'until' as inclusive date bounds in YYYY-MM-DD and 'samples' as disagreements to sample per language with a max of 50. It omits the schema's default of 15 for samples and doesn't clarify what happens if since > until or if the max is exceeded (clamped vs. error).

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?

Opens with a specific verb+resource: 'Compare primary engine and second reader per language', and enumerates the comparison dimensions (agreement, calibration, samples). This clearly distinguishes it from siblings like voicememos_second_read (which presumably produces one reading) and voicememos_transcribe, 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 only implied by the phrasing 'compare primary engine and second reader', suggesting it is run after a second read exists. There is no explicit statement of when to use it, when not to, or which sibling to call first to populate the second 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?

With no annotations, the description carries the full burden. It discloses the default ordering ('newest first') and explains the meaning of each status value, which is genuinely useful behavior context. It does not state that this is a read-only/non-destructive operation, nor describe the returned fields or pagination edge cases (e.g., offset without limit).

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

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

The first sentence front-loads the purpose and ordering, and the arg list is compact. The verbose `status` explanation is justified because the schema has no enums, though it makes the block slightly long.

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 six-parameter list tool with no annotations and no output schema, the description covers filtering semantics but omits safety profile (read-only), shape of returned memo records, and how paging interacts with ordering. Adequate but not 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 0%, and the description compensates well: it documents all six parameters, gives date formats for `since`/`until` (YYYY-MM-DD), clarifies substring/case-insensitivity for `title`, and enumerates the meaningful `status` values with explanations. Minor ambiguity remains about whether `status` accepts a single value or a list, and the `limit` default of 20 is only in 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?

Names a specific verb and resource ('List memos') and adds ordering ('newest first'), which an agent can act on immediately. It does not, however, distinguish this from the sibling `voicememos_search`, so the agent must guess which listing tool to choose.

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

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

There is no explicit statement of when to use this versus `voicememos_search` or the read/status siblings. The filter parameters imply a browsing use case, but the agent is left to infer that from the arg docs alone.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it never states that this is a read-only operation, whether results are ordered, how pagination beyond the limit behaves, or what the output records look like. The marker concept is explained, which is useful, but core behavioral traits are 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?

The core definition is front-loaded in a single sentence with a concrete example, followed by a tightly formatted Args list. No wasted sentences, though the concept sentence could state the retrieval action more explicitly.

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 and no annotations, the description should say more about the return shape, ordering, and pagination. It explains what markers are and how to filter, which is adequate minimum context for a simple query, but not 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 0%, so the description must compensate, and it does define all four parameters with useful meaning: since/until bounds with YYYY-MM-DD format, label as a filter, and limit as maximum markers returned. The default limit of 50 is not stated, and case-sensitivity of label is unspecified, keeping it from a 5.

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 identifies the resource: sentences the user tagged with a spoken marker word, with an illustrative example. It distinguishes itself from siblings like voicememos_list or voicememos_search by being specifically about tagged markers, though the retrieval verb is only implied rather than stated.

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

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

There is no guidance on when to use this tool versus voicememos_list, voicememos_search, or voicememos_read. The agent must infer from the name and the marker concept alone. No prerequisites or exclusions are stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses that changing the threshold re-renders without re-transcribing, that long transcripts are paginated via offset/max_chars with a 1000-100000 bound, and that three output formats exist. It stops short of stating read-only semantics or rate/auth constraints, but the key behavioral traits are covered.

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 purpose is front-loaded in one sentence, then parameters are listed compactly with no filler. The Args block is slightly verbose but every line carries information an agent cannot get from the schema.

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 tool with no output schema, this describes the return content (transcript with uncertainty marks, header in markdown) and pagination behavior. The dangling 'next_offset' reference and the absence of any statement about what json word-level data looks like are minor omissions.

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

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

Schema coverage is 0%, so the description must document all five parameters, and it does: memo accepts an 8-char prefix, format enumerates markdown/text/json, threshold defaults from config and only re-renders, offset is a character offset, and max_chars has an explicit range. The only gap is that offset references a 'next_offset' value that is never defined, since no output schema exists.

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

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

The first line states a specific verb and resource: read one transcript, with the distinguishing trait of uncertainty marks. It is clearly not list/search/compare, but it doesn't explicitly contrast itself with the closest sibling read tool, voicememos_second_read.

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 through the prerequisite chain ('memo id from voicememos_list') and through the pagination hint ('see next_offset'), but there is no explicit when-to-use-this-versus-alternative guidance against second_read or compare_readers.

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

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

With no annotations, the description carries the full behavioral burden: it discloses case-insensitivity, regex mode, snippet returns, and inclusive date-bound semantics. It does not state that the operation is read-only, whether results are ranked or truncated beyond 'limit', or any cost/rate considerations.

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 behavior sentence is front-loaded and the per-argument list is terse with no redundancy. Every line maps to a distinct parameter or behavior.

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 and no annotations, the description adequately covers inputs and the return shape ('snippets per memo'). Minor gaps remain around result ordering, pagination/offset behavior, and whether the date filters apply to recording or transcription time.

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

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

Schema coverage is 0%, so the description has to compensate and largely does: every one of the 5 parameters is explained, with explicit YYYY-MM-DD formats for since/until and the interaction between query and regex. Only limit's default (20 in schema, absent from description) is left implicit.

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 opening sentence gives a concrete verb and resource ('Search transcripts and titles'), adds the case-insensitive trait, and says what comes back ('snippets per memo'). It doesn't distinguish itself from siblings like voicememos_list or voicememos_read, so an agent must infer the boundary.

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?

Search-by-text usage is implied by the tool name, field targets, and regex option, but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to voicememos_list for unfiltered enumeration. An agent could plausibly pick list over search for a keyword 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses asynchronous queuing and a returned job_id, the output format of disagreements ({a|b}), redo semantics, the realign mode that performs no new reading, and edge behavior for long recordings under only_uncertain. It stops short of mentioning permissions or how to poll the queued job.

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 purpose is front-loaded in the first sentence, followed by an organized Args list. It is appropriately sized for an eight-parameter tool, though the 'or:' formatting in since/until is slightly awkward and a few notes could be tightened.

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 an async job tool with no output schema, the description provides the essential return value (job_id), all parameter semantics, and important behavioral modes. It could be more complete by noting that memos must already be transcribed, what happens if they are not, or which sibling status tool to use to retrieve the job result.

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

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

Schema description coverage is 0%, so the description must compensate for all eight parameters, and it does: memos, since, until, model, redo, limit, only_uncertain, and realign are each explained with meaning and important nuances (date filtering is OR, limit applies oldest first, long recordings only in low-certainty parts).

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 action — queue a second, independent Gemini reading — on a specific resource: already transcribed memos. It also distinguishes the outcome from the primary engine by explaining that disagreements appear as {a|b} in the transcript, making it identifiable against siblings like voicememos_read or voicememos_compare_readers.

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 'second, independent reading' and 'already transcribed memos', and parameter notes (redo, realign, only_uncertain) somewhat guide behavior. However, there is no explicit guidance on when to prefer this over voicememos_compare_readers, voicememos_read, or when a second reading is unnecessary.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the categories of information returned, which is useful, but does not state that the tool is read-only, side-effect-free, or whether any permissions or rate limits apply.

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

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

The description is a single, front-loaded sentence with no wasted words. It is essentially a noun phrase rather than a full sentence, but every item listed 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 zero-argument status tool, the description adequately names the returned categories, but without an output schema it leaves the return format and granularity (aggregate counts versus per-file details) unclear. It also does not help an agent choose it over voicememos_transcribe_status.

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

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

The tool takes zero parameters, so the schema imposes no additional semantic burden. The description appropriately does not discuss parameter syntax.

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 enumerates the specific status content returned: library size, transcription status counts, worker health, and configuration. It is clear what the tool reports, though it does not explicitly differentiate itself from voicememos_transcribe_status.

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 listed contents imply a diagnostic or overview use case, but there is no explicit guidance on when to use this versus voicememos_transcribe_status or other status-adjacent siblings.

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

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

With no annotations, the description carries the burden well: it discloses asynchronous background execution, an immediate job_id return, the default skip-if-transcript-exists behavior implied by redo, and the conditional Roam side effect. It omits failure behavior, cost/rate implications of transcription, and how to check job completion.

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

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

Front-loaded with the two facts an agent needs (what it does, what it returns), then a scannable Args list. The stray 'or:' artifacts and blank-line formatting add mild noise but nothing is wasted.

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

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

For a 5-parameter, no-annotation, no-output-schema tool, the description covers the async contract, the return value, and every parameter's meaning. The main missing piece is the follow-up workflow for the returned job_id, which matters for a background job tool.

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

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

Schema coverage is 0%, so the description must compensate and largely does — it explains all five parameters including the YYYY-MM-DD date format, the redo semantics, and that push_roam only applies if Roam is configured. Minor gaps: no statement that memos and since/until are alternatives, and the 'or:' phrasing is garbled.

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+resource+mode: 'Queue memos for transcription in the background', plus the immediate return value 'job_id'. That clearly separates it from voicememos_transcribe_status and voicememos_read, though no sibling is named explicitly.

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

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

The Args block implies two selection modes (explicit memo ids vs. since/until date range) and flags redo for re-transcription, which gives usable context. However, it never says when to prefer this over alternatives, nor does it point to voicememos_transcribe_status for polling the returned job_id.

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

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

No annotations exist, so the description carries the full burden. It does disclose a real behavioral trait beyond the name — the default of returning the 10 most recent jobs when job_id is omitted — but says nothing about read-only nature, what 'progress' values look like, or whether terminal states (completed/failed) are distinguishable.

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 primary mode and finishing with the conditional fallback. Nothing is wasted and the branching condition is stated precisely.

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 optional-param read tool this covers both invocation modes, but with no output schema and no annotations, an agent still cannot tell what a 'progress' response contains or how to detect completion — the key question for a status tool.

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

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

Schema description coverage is 0%, so the description must compensate for the single job_id parameter, and it does: it explains the omission case and the result-set cap. It does not describe the expected job_id format or where an agent obtains one, leaving a small gap.

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?

Names the resource ('transcription job') and the information returned ('progress'), and the fallback behavior makes the dual mode explicit. It does not reference the sibling voicememos_transcribe, which submits jobs, so the agent must infer the pairing 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?

The dual-mode sentence implies you call it with a job_id to poll progress and without one to list recent jobs, but there is no explicit when-to-use guidance, no note that it should be called after voicememos_transcribe, and no mention of a sibling for other listing needs.

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

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

With no annotations, the description must carry behavioral disclosure, and it does disclose meaningful traits: processing is local, the other-voice entry is 'never shown by name' (a privacy/semantics guarantee), and name defaults from config. It stops short of saying what enrollment persists, what each action returns, or how failures are reported — notable gaps for a state-mutating action set.

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 one-line purpose is front-loaded and the Args block is organized rather than rambling; every clause carries actionable detail. It is slightly verbose in the parentheticals ('e.g. a relative who sounds similar'), but no sentence is pure 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?

Six parameters, no annotations, and no output schema means the description is the only source of truth, and while parameters are fully explained, the return shape of 'status' and 'identify' is only hinted at ('enrollment state, thresholds and suggested enrollment memos'). An agent can invoke it correctly but cannot predict what comes back or what errors to expect.

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

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

Schema coverage is 0%, so the description does all the work, and all six parameters are documented with per-action scope: 'memos' means different things for enroll/identify/add_other, 'since'/'until' are restricted to 'identify' with a YYYY-MM-DD format, and 'name'/'speaker' are disambiguated by action. This is exactly the compensation a 0% coverage schema requires.

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

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

Opens with a specific verb and resource: 'Recognise the owner's voice with a local voiceprint,' and the Args block enumerates five mutually exclusive actions, which frames the tool's full scope. It doesn't explicitly name or contrast with siblings (voicememos_transcribe, voicememos_second_read), but the voiceprint domain is distinctive enough that confusion is unlikely.

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?

Each action carries its own when-to-use condition: 'enroll' requires memos where only the owner speaks, 'identify' applies to already transcribed memos, 'add_other' exists specifically to prevent mistaking a similar-sounding relative for the owner. It even specifies data thresholds (2+ memos, ideally 4-6 from different years) and that 'speaker' is only needed for multi-speaker memos, leaving little to inference.

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