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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=false) but say nothing about errors or side effects. The description adds real behavioral context beyond that: a 409 means the job exists but is no longer awaiting naming, and it explicitly scopes out voice-database enrollment.

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, front-loaded with the action and its effect, then error semantics, then scope exclusion. No sentence is redundant and nothing is buried.

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

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

For a two-parameter mutation with no output schema and annotations that cover the safety hints, the description supplies the missing pieces an agent needs: the 409 condition and the explicit non-enrollment boundary. It does not say what a successful response looks like, but that gap is minor.

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

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

Schema description coverage is 100% and already explains both jobID and the label-to-name mapping, including 'Read the labels from get_naming first.' The description reinforces the diarization-label framing but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('confirm the real names behind a job's diarization labels') and the consequence ('so it can finish'), which tells the agent exactly what effect the call has. It is clear but never names the sibling it pairs with (get_naming), so discrimination from skip_naming rests on the schema rather than the description.

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 'a job's diarization labels' and the 409 note, which tells the agent the call only applies while a job is awaiting naming. There is no explicit 'call this after get_naming' or 'use skip_naming instead if' guidance in the description itself.

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=false and idempotentHint=true, and the description adds genuinely non-obvious behavior: the call is asynchronous and jobs can 'park' on a speaker-naming step requiring a separate resolution. It stops short of covering failure modes or what happens with duplicate/invalid paths, so it is strong but not exhaustive.

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, front-loaded with the core action and outcome, then the follow-up workflow and the sibling contrast. 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 output schema, the description still states what comes back (job ids) and outlines the full downstream lifecycle (poll, resolve naming). Nothing essential for invoking and using the result 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 both parameters (paths, idempotencyKey) are already documented in the schema. The description only reinforces plurality ('one or more') and adds no syntax or format detail beyond that, matching the baseline for schema-documented params.

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+resource ('Queue one or more audio files') and states the immediate outcome (returns job ids). It explicitly differentiates itself from the sibling transcribe_file, so an agent can route without opening either schema.

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

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

Gives explicit next steps (poll with get_job) and the alternative resolution paths (confirm_naming or skip_naming), plus a direct contrast with transcribe_file. This is when-to-use and what-to-do-next guidance, not just implied context.

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

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

Annotations already declare readOnlyHint=true, and the description adds substantial non-obvious behavior: 404 causes (never enqueued, aged out, cancelled before finishing) and the fact that an errored job is not always final because a manual retry moves the same id back to waiting. That lifecycle detail is exactly the kind of context annotations cannot carry.

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, front-loaded with the core purpose, then increasingly specific lifecycle facts. No filler, no restatement of the name, and each sentence carries distinct operational 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?

With no output schema, the description compensates by naming what is returned (state, result paths, transcript) and by explaining error/retry and 404 semantics. For a read-only three-parameter tool, nothing an agent needs to call it correctly appears to be 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 every parameter including includeProtocol and includeTranscript is already documented, and the schema itself notes that running jobs have no transcript. The description repeats that point but adds no new syntax, format, or default information beyond the schema, 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 ('Read a job's state, result paths and transcript') and enumerates what the read returns. This clearly separates it from siblings like enqueue_files (creates) and transcribe_file (starts work), so an agent can pick it without opening the 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?

Explains the contexts in which reads succeed (live jobs and jobs the app has already reaped) and what a 404 implies, which tells the agent when a result is meaningful. It does not name an alternative tool or an explicit when-not-to-call condition, so it stops short of full routing guidance.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds real value beyond them: the state-dependent 404 behavior and the deliberate omission of voice embeddings and audio. It stops short of describing response shape or whether the pending set is paginated, but the safety and failure profile is well 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?

Three compact sentences: what is returned, when it is valid, and what is intentionally excluded. The scoping constraint is front-loaded and no sentence is 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 output schema, the description carries the return-value burden and does so by naming the suggestion and per-speaker duration, and it covers the failure mode and exclusions. For a single-parameter read tool, an agent has everything needed to call 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?

Schema coverage is 100%, so jobID's type and requirement are already documented, which sets the baseline at 3. The description adds meaning beyond the schema by stating that the job must be in the speakerNamingPending state for the parameter to be usable, tying the argument to a runtime precondition.

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 (read) and resource (speaker labels awaiting naming) plus the payload contents (app suggestion, per-speaker duration). It is clearly distinguished from the sibling writers confirm_naming/skip_naming without needing to name them, since the pending-read framing implies the write counterparts.

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 scopes usage: only meaningful while the job is in speakerNamingPending, and other states return 404. That is a clear use condition, though it never names an alternative tool (e.g., confirm_naming to finalize) or what to do instead when the state is wrong.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context beyond that: polling is cheap, the call succeeds even while the app is starting up, and it doubles as an API liveness check — genuinely useful operational traits.

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

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

Two sentences, both front-loaded with the return contents first and the operational guidance second. Slightly dense in the second clause, but every phrase (poll cost, startup availability, liveness role) carries information an agent would otherwise lack.

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 input parameters and no output schema, the description carries the burden of describing what comes back — and it does, listing watch state, badge, and permission health. Nothing needed to call this zero-arg read tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% with an empty object schema, leaving no gaps.

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 read verb and enumerates the exact resource facets returned: watch state for Teams/Zoom/Webex, menu bar badge, and permission health. This is immediately separable from set_watch and the transcription siblings, which operate on jobs and files rather than app state.

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

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

Gives clear usage context ('cheap enough to poll', usable as a liveness check for the automation API) and notes it works during startup. It does not explicitly name set_watch as the mutating counterpart, so the alternative routing is implied rather than stated.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, openWorldHint=false), and the description adds genuinely new behavioral context: a 409 signals that a manual recording owns the watch loop, and a first start on a fresh install can trigger a macOS microphone/screen-recording prompt requiring interactive grant. These are exactly the failure modes an agent cannot infer from the structured fields.

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

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

Three tight sentences, front-loaded with the core action and followed by error and permission context in priority order. 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?

No output schema exists, but for a one-parameter toggle the description covers the operation, the key error case, and the external permission prerequisite. Nothing an agent needs to 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?

Schema description coverage is 100% and the single 'action' enum is richly documented in the schema itself (including why toggle is omitted). The description adds nothing beyond that, 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 (start/stop) and resource (automatic meeting detection / watch loop), and anchors it to a concrete UI equivalent ('the same thing the menu bar's Start Watching item does'). An agent can separate this from get_watch_status (read-only status) 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 clear context for invocation (start vs stop, the 409 conflict case, and the interactive-permission prerequisite before relying on it). It does not explicitly route to a sibling alternative such as get_watch_status for checking state first, so it stops short of full when/when-not guidance.

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

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

The annotations already indicate this is a non-read-only, non-idempotent operation, so the description adds useful behavioral detail by explaining that a 409 response means the job exists but is no longer awaiting naming. It does not disclose auth requirements, but the error-state semantics go beyond the structured 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 concise sentences with no wasted words. The main effect is front-loaded, and the 409 detail follows as a useful secondary point.

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 action tool with annotations and full schema coverage, the description covers the core action and one notable error state. It remains thin on workflow context, particularly how this tool relates to sibling tools such as confirm_naming and get_naming.

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 parameter jobID is already defined as 'The job awaiting speaker naming.' The description does not add any syntax, format, or additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific effect — allowing a job to finish using the app-assigned speaker names — which is a clear skip-naming action. It is understandable apart from the tool name, though it does not explicitly contrast itself with similar naming tools like confirm_naming.

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 used when the caller wants to accept auto-assigned names, but it gives no explicit when-to-use condition or alternative. It also does not tell the agent when to use confirm_naming or get_naming instead.

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?

Adds substantial behavior context beyond annotations: 'runs headless,' auto-assigned speaker names, no parking on the naming step, and the idempotency/dedup semantics are reinforced. Annotations declare idempotentHint=true, which the description aligns with rather than contradicts.

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, no filler, front-loaded with the primary action, then behavioral note, then alternative routing. 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?

Completes the picture for a mutation-side submitter: how it behaves (headless, speaker naming), how it differs from siblings, and timeout semantics via schema. No output schema, so it does not need to describe return shape, and the schema handles return-adjacent details like includeTranscript.

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 all four parameters are already documented in the schema, including the path-absolute/local-machine restriction and idempotency reuse guidance. The description adds little param-specific syntax or format detail beyond what the schema provides; 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?

States a precise verb+resource+scope: submit one audio/video file to Meeting Transcriber and wait for the diarized transcript. Clearly contrasts with enqueue_files and get_job as the non-blocking alternative.

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

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

Explicitly names enqueue_files plus get_job as the alternative and gives the condition (not wanting to block, or wanting to assign speaker names yourself). It does not cover when blocking itself is inappropriate, but the routing guidance is clear.

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