Lunara

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds two useful facts beyond that: this call kicks off the downstream pipeline (a real side effect) and it returns a job id for polling. It does not say whether the completion is final/irreversible or what happens on a stale parts list, so it is a modest addition rather than rich behavioral context.

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, no filler, and the action-plus-consequence comes before the return/polling instruction. Every clause earns its place and nothing is redundant with the annotations.

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 five required parameters, no output schema and no nested objects, the description covers the essentials: what triggers the call, that it starts processing, and that the return is a job id to poll. It leaves minor gaps around the multipart-completion semantics (e.g. whether parts must be listed in order), but those are largely implied by the 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?

Schema description coverage is 100% and every one of the five required parameters carries its own description, including the {PartNumber, ETag} part structure and the cross-reference to lunara_upload_video for videoId. The description adds no parameter-level detail 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 concrete action (notify Lunara that the bytes are uploaded) plus the consequence (pipeline starts), which is specific enough to separate it from lunara_upload_video and lunara_start_subtitle_job. It also names the return value, so an agent knows this is a terminal step of a multipart upload rather than a generic job starter.

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?

"Tell Lunara the bytes are uploaded so the pipeline can start" gives the triggering condition, and "poll with lunara_get_job" explicitly routes the agent to the correct follow-up sibling. It stops short of stating prerequisites (e.g. all parts uploaded via lunara_upload_video) or exclusions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond that: it reports a coverage measure and lists gaps only when they are longer than a second, which tells the agent what to expect in the result without a contradiction.

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

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

Two tight sentences with no filler. The purpose is front-loaded and the usage guidance follows immediately.

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 usefully states what the report includes: a coverage amount and suspicious gaps longer than one second. It stops short of describing the exact return shape or how coverage is expressed, but it is sufficient for an agent to call the tool 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?

There is only one parameter (jobId) and schema coverage is 100%, so the schema already explains it as 'The job to inspect.' The description does not add further detail about jobId, so the 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 gives a specific verb ('Report') and resource (coverage of the source timeline by subtitles), and adds what the report contains: coverage amount plus a list of gaps over one second. This clearly separates it from siblings like lunara_qa_contract or lunara_readability, which are not about timeline coverage.

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 recommends using the tool 'before shipping a long video,' giving a clear context for invocation. It does not name an alternative tool or an explicit when-not-to-use condition, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the semantic purpose, saying nothing about what happens with an empty glossary, how the limit caps results, or whether terms are versioned — gaps that matter less here because the annotations carry the 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?

One sentence, action first, rationale second, zero filler. Nothing could be removed without losing either the resource or the motivating use case.

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, one-optional-parameter tool with no output schema, the description is largely sufficient: it identifies the resource and its intended use. A brief note on the returned shape (a term list) and on behavior when the glossary is empty would close the remaining gap.

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

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

There is a single optional limit parameter with 100% schema description coverage (default 100, max 500), so the schema already carries the semantics. The description contributes nothing about limit — no hint about truncation or how to page beyond the cap — which is acceptable at baseline 3 when coverage is complete.

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 ("Return") and a specific resource ("the proper nouns Lunara has learned for this org"), plus the downstream purpose of consistent spelling. It does not, however, name or distinguish itself from the sibling lunara_glossary_extract, so an agent must infer that this reads an existing glossary rather than building one.

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 trailing clause "so names are spelled consistently across tracks" implies the context in which to call it (before translation/rewrite/segmentation work), but there is no explicit when-to-use statement and no exclusion pointing at lunara_glossary_extract as the alternative when no glossary exists yet. Usage is inferable 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: the returned fields (including cue count and SRT readiness) and the polling pattern. It doesn't describe terminal/failure states or error behavior, so not a 5.

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

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

Two sentences, zero filler, with the resource and returned fields front-loaded ahead of the usage hint. Nothing could be removed without losing information.

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

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

With no output schema, the description usefully enumerates what comes back, and the single-parameter schema needs little more. A gap remains around status values and what to do when the job fails or the SRT is not yet ready, which matters for a polling 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 100% and the single parameter is fully documented in the schema as 'the job id returned by lunara_upload_video'. The description adds no new syntax, format, or sourcing detail 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 and resource ('Return the state of a subtitle job') and enumerates the exact payload fields (status, progress, SRT readiness, cue count). This enumeration is what separates it from neighbors like lunara_get_srt and lunara_list_cues, which return content rather than job 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?

'Poll this after lunara_upload_video' gives a concrete trigger, sequencing, and the fact that repeated calls are expected. It stops short of naming when-not to use it or pointing at the sibling to call once the SRT is ready (lunara_get_srt), so no explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful format context ('one line per cue', English default for secondary) but doesn't say whether the result is returned inline as text or as a path/URL — a real behavioral gap for a download-style tool.

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, then format, then the key parameter caveat. No wasted text.

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 gives the essential return characteristic (one line per cue) plus the track default. The only missing piece for full completeness is whether the response is raw file content or a handle/URL.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that "secondary" is the translated track and that English is the default, which the schema's enum description does not state. jobId is left to the schema.

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

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

States a specific verb ('Return') and resource ('subtitle file for a finished job') with the format (SRT) implied by the name and 'one line per cue'. It's clearly distinct from list_cues or get_job, though it never explicitly names an 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?

The phrase 'for a finished job' implies a precondition, and it helpfully points to track="secondary" for the translated track. However, it doesn't say what to do if the job isn't finished or direct the agent to a sibling for the non-file case; usage is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: results are heuristic candidates ranked by frequency, each carrying the first cue of occurrence, and the tool performs no rewriting — warning the agent that output is a suggestion set, not ground truth.

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

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

Two short sentences, no filler; the core action and the frequency/first-cue output shape are front-loaded, and the non-destructive caveat closes it.

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 the description sketches the return shape (ranked terms plus first cue). Combined with full schema coverage and rich annotations, an agent has enough to call it correctly; only the exact result envelope is unspecified.

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 both parameters (jobId, limit with default 50 and max 200) are documented inline, so the baseline is 3. The description adds only the frequency ranking and first-cue payload context, not parameter-level 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?

States a specific verb and resource ('find candidate proper nouns in a job's cues') plus the ordering and payload ('ranked by frequency, with the first cue they appear in'). The closing clause 'Suggestions for a glossary, not corrections' implicitly separates it from lunara_get_glossary and lunara_rewrite, though neither 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?

'Suggestions for a glossary, not corrections — nothing is rewritten' gives a contextual hint about intent, but there is no explicit statement of when to call this versus lunara_get_glossary (reading an existing glossary) or lunara_rewrite. The agent must infer the routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's real contribution is the return format 'timestamps plus text' — material because there is no output schema. It omits pagination behaviour and whether cue identifiers are included, which are the remaining behavioural unknowns.

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

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

A single front-loaded sentence that states the resource, the result shape, and the motivating use case with no filler. Nothing could be removed without losing 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?

For a three-parameter read tool with no output schema, the description supplies the essential missing piece — what comes back. Ordering, default paging behaviour, and the distinction from lunara_get_srt remain unaddressed, keeping it short of fully complete.

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

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

Schema description coverage is 100%, so jobId, limit with its 500 cap, and offset are fully documented in the schema. The description adds nothing about parameters, which is acceptable at this coverage level but is the baseline rather than an improvement.

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

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

Specific verb (return) plus resource (subtitle cues for a job) with the notable extra that it names the output shape, timestamps plus text. It does not distinguish itself from siblings such as lunara_get_srt, which plausibly returns the same content in a different form.

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 trailing clause 'so you can inspect or reference individual lines before proposing edits' implies a workflow position (read-before-write), which is useful. But it never states when to prefer this over lunara_get_srt or the edit/rewrite tools, and gives no exclusions or prerequisites such as the job needing to be completed.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful behavioral context by saying the result includes minute costs and that this tool should be called first for discovery.

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 concise sentences, front-loaded with the return content and followed immediately by the usage condition. No sentence is redundant.

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 discovery tool with annotations covering safety and no output schema, the description provides enough: what is returned, that costs are included, and when to call it. 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 tool has zero parameters, so there are no parameter semantics to explain. The description correctly does not waste space on parameters, matching the baseline for param-less tools.

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: return every subtitle tool Lunara exposes, and adds that each tool's minute cost is included. This clearly distinguishes it as a discovery/catalog tool from all sibling processing tools.

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

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

It explicitly says to call this first when unsure which tool fits, giving clear trigger context. It does not name a specific alternative or state when not to use it, but for a discovery tool the guidance is 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 declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuine value beyond that by disclosing the returned fields and the specific mono/16 kHz pre-check that drives engine selection. It does not mention failure behavior for unreachable URLs, which would be useful given openWorldHint.

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, nothing redundant: outputs first, then the call-to-action ordering hint. Every clause carries information an agent needs.

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

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

With no output schema, the description usefully enumerates return fields, so the agent knows what it will get back. The only gap is error/unreachable-URL behavior for an open-world read against an arbitrary remote URL.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines mediaUrl fully. The description only echoes 'for a URL' and adds no format, scheme, or size constraints beyond it.

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

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

States a specific verb (probe/return) and enumerates the exact resources produced: duration, dimensions, codecs, container, plus a mono/16 kHz flag. This clearly separates it from sibling media tools like lunara_transcribe or lunara_start_subtitle_job, though those siblings are never named.

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

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

"Call this before choosing an ASR engine" gives a concrete ordering/precondition, which is real usage guidance. It stops short of naming the alternative tools or stating when to skip it (e.g., when metadata is already known).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it returns pass/fail per rule and is free of charge, which matters because a caller might otherwise hesitate to validate repeatedly. It stops short of saying what happens on failure (does it block lunara_finish_upload?).

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, no waste. The rule list is front-loaded as the core purpose and the pricing note is a compact trailing clarification.

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 read-only check with no output schema, the description tells the agent what it validates and what it returns at a granularity level. What's missing is downstream behavior on failure and any precondition on jobId (e.g., job must have finished segmenting/transcribing).

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

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

Schema coverage is 100%, so the schema fully documents jobId and the track enum. The description's 'both tracks' is consistent with the schema default but adds no format or selection guidance beyond it, which fits the baseline of 3.

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 (run the contract gate) and resource (subtitle tracks), and enumerates the exact rules checked: byte-exact ASR text/timings, cue length bounds, no empty cues. This clearly separates it from validation-adjacent siblings like lunara_readability and lunara_get_coverage.

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

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

The phrase 'contract gate' implies it belongs before finalizing/delivering a track, and 'both tracks' hints at the default scope, but there is no explicit when-to-use guidance and no named alternatives such as lunara_readability or lunara_get_coverage. Usage is inferable but not 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context about what is computed and that the numbers mirror the editor, but it says nothing about failure modes (unsegmented job), whether thresholds are configurable, or cost of the computation.

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

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

Two sentences, zero filler, and the core content (what is measured) leads before the secondary note about the editor mirroring. Nothing could be removed without losing information.

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

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

With no output schema, the description does a reasonable job of sketching the return payload (per-cue metrics plus over-limit cues), but omits the unit conventions, whether severity thresholds are exposed, and the preconditions for a valid job. Adequate, 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 100% with only two parameters, so the schema already explains jobId and the primary/secondary track enum. The description contributes no additional meaning about either parameter, which is exactly the baseline case.

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 definition names the exact metrics returned (per-cue reading speed, displayed length, characters-per-second) and adds the flagging behavior for cues exceeding limits, which separates it from lunara_list_cues and lunara_qa_contract. It is a noun phrase rather than an explicit verb+resource statement, and it never says the metrics are computed for a subtitle job's cues, but that is inferable from jobId and the sibling set.

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 when-to-use guidance at all: no mention of when readability checking should happen in the pipeline, no reference to lunara_list_cues, lunara_qa_contract or lunara_get_coverage as alternatives, and no prerequisites such as the job having been segmented or transcribed first.

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 non-destructive (destructiveHint=false) and idempotent (idempotentHint=true); the description adds genuinely non-obvious behavior: cue boundaries and timestamps are preserved, mispronunciations are deliberately left uncorrected, and proper nouns are protected. What is missing is whether it writes back into the existing cues in place (readOnlyHint=false implies mutation) or produces a new track/artifact.

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 front-loaded sentences, each carrying a distinct fact (transformation, structural preservation, linguistic exception rules). No filler or restatement of the title.

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 mutating tool with no output schema, the agent still lacks the mutation shape: does it overwrite the job's cues or create a new version, and can it be re-run against its own output? The behavioral notes are useful but the write semantics are unstated.

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% with clear per-parameter descriptions for jobId and track (enum primary/secondary), so the schema carries the load. The description adds nothing about the parameters — e.g., whether track selects input, output, or both — so baseline 3 applies.

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

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

States a specific verb+resource+transformation: spoken Cantonese cue text → written Chinese. An agent can tell what the operation does. It does not name or contrast with the closest sibling, lunara_translate, which is the one plausible confusion for this tool.

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 never says when to use this versus lunara_translate or where it sits in the pipeline (after transcription/segmentation?). The phrase 'cue text' only weakly implies cues must already exist. No prerequisites, ordering, or exclusions are given.

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

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

Annotations confirm non-destructive and idempotent behavior, but the description adds critical context beyond them: the split is approximate, proportional to character count, does not change words, and produces estimated timings. These limitations directly affect how an agent should interpret and use the result.

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 definition is front-loaded with the key caveat, 'Approximate split, not audio-grounded segmentation,' then explains the algorithm and alternative in a compact paragraph. Every sentence contributes useful information, including the limitation and routing 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 non-destructive, idempotent cue-splitting tool without an output schema, the description provides the behavioral details an agent needs: approximation method, word preservation, and estimated timings. It also routes agents to the correct alternative when accurate timing is required.

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, track, and maxCueMs are already fully documented in the schema. The description explains the splitting algorithm conceptually but does not add syntax, constraints, or defaults beyond what the schema provides. A baseline 3 is appropriate when the schema does the parameter-level work.

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

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

The description states a specific operation: cue text is divided at clause punctuation and each piece receives a proportional share of the original span. It explicitly distinguishes this approximate split from audio-grounded segmentation and names the sibling tool for audio-derived timing. An agent can tell exactly what this tool does and does not do.

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 explicit usage guidance: treat timings as a reading aid rather than a re-alignment, and use lunara_start_subtitle_job if timing must be derived from audio. This names both the condition and the alternative, leaving no ambiguity about when to select this tool.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the safety and side-effect profile is covered structurally. The description adds the useful fact that this is a heavyweight eight-layer pipeline producing two tracks, but omits that it is asynchronous and that results must be retrieved via lunara_get_job / lunara_get_srt — a material gap for a tool whose name is 'start ... 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?

Three short sentences, front-loaded with the action and its output, then the routing caveat. Nothing is padded and no sentence is redundant.

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 four params, no output schema, and non-idempotent job-start semantics, the description should say what comes back (a job handle) and how to get subtitles. It covers inputs and outputs conceptually but leaves the async lifecycle — the part an agent most needs — to inference from sibling names.

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%: audioUrl, spokenLang, primaryLang and secondaryLang each carry their own description and two have enums, so the schema does the heavy lifting. The description only reinforces audioUrl with 'a URL you can already host', adding marginal meaning beyond the schema's 'public or pre-signed'.

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 concrete verb and resource ('Run the full eight-layer subtitle pipeline on an audio or video URL') plus the two artifacts it produces, which is far more than a restatement of the name. It differentiates from lunara_upload_video by input source, but leaves the near-identical sibling lunara_subtitle_from_url completely unaddressed, so an agent still cannot fully disambiguate.

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?

'Prefer lunara_upload_video when the file is local' is an explicit alternative with the selecting condition, which is exactly the right shape of guidance. However, the closest alternative (lunara_subtitle_from_url) is never mentioned, so the most likely wrong-tool choice remains unguided.

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 valuable behavior beyond the annotations: the operation is asynchronous, returns a job id, persists a job, and must be polled at a specific cadence. It does not discuss job expiry, failure modes, or permission requirements, but with annotations already declaring non-read-only, non-idempotent, open-world behavior, the added workflow context is substantive.

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 front-loaded with the core action and is only three sentences long. Every sentence adds useful information: the action, the return value and polling workflow, and the sibling-tool preference.

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 appropriately explains that a job id is returned and describes the polling and retrieval steps needed afterward. Combined with the rich input schema and annotations, it gives an agent enough context to invoke and follow up 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 description coverage is 100%, so all five parameters, including enums, are already documented in the schema. The description adds only contextual wording such as “URL you already host,” without parameter-specific details beyond the schema, making the baseline 3 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: start a persisted subtitle job from a URL. It clearly distinguishes this from upload-based flows by saying no upload is needed and by naming lunara_upload_video as the alternative.

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

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

It gives explicit usage guidance: prefer this over lunara_upload_video whenever media is reachable by URL. It also describes the follow-up workflow, polling lunara_get_job every 15–30 seconds and then calling lunara_get_srt.

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

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

Annotations already cover the safety profile (idempotent, non-destructive, open-world), so the description's added value is the stage-isolation semantics and the return shape ('returns timed segments'). It does not say whether the call is synchronous or returns a job to poll, which matters given the lunara_get_job sibling — that is the one meaningful behavioural gap.

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 capability and the exclusion, then the return value, then the selection rule. No filler or restatement of the title.

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 tool with no output schema, the description supplies what the schema cannot: what comes back (timed segments) and that this is a single pipeline stage. The remaining omission is job/lifecycle behaviour, which an agent calling a transcription service likely needs to know.

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 both parameters (audioUrl, spokenLang) are documented in the schema itself. The description adds nothing about either input, which is acceptable at full coverage but is the baseline, not a contribution.

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 ('Run speech recognition') and immediately scopes it by negation — 'no rewrite, no translation' — which separates it from lunara_rewrite and lunara_translate. An agent can pick this over its siblings without opening any schema.

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

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

'Use this when you want the transcript itself, or when you plan to pick a later stage yourself' gives a clear positive selection condition. It doesn't name the specific alternative tools (lunara_subtitle_from_url, lunara_start_subtitle_job) for the case where the caller wants the full pipeline in one shot, so routing is implied rather than explicit.

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 real context beyond the annotations: every cue boundary and timestamp is preserved, only text changes, which tells the agent exactly what the mutation touches. It does not say whether the translated text replaces the source track or is written to a new track, a meaningful gap for a readOnlyHint=false operation.

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

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

Two short sentences with zero padding, front-loading the action and then the guarantee that matters. Nothing repeated from the schema or annotations.

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 3-parameter mutation tool with full schema coverage and annotations, the description covers purpose, timing guarantee, and the reason to prefer it over manual translation. The remaining ambiguity about output (new track vs in-place) and return value is the only real shortfall, and no output schema exists to cover 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?

Schema coverage is 100%, so jobId, track, and targetLang are all documented with enums for the latter two. The description reinforces that jobId refers to an existing job but adds no new semantics about the track parameter or language options; 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: translating the cue text of an existing job into another language, plus a precise scope note that only text changes. It does not explicitly differentiate itself from sibling lunara_rewrite, which also mutates cue text, so the agent must infer the distinction from 'into another language'.

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?

'Use this instead of translating yourself so the timing contract holds' gives a clear selection rule against the main alternative (agent-side translation). It stops short of naming sibling tools or stating when-not to use it (e.g., when a rewrite rather than a translation is wanted).

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 the safety profile (non-read-only, non-destructive, not open-world), so the bar is lower, and the description meaningfully adds the multi-step contract: it returns per-part signed URLs and requires a follow-up finish call. However it omits behavior an agent needs for failure handling – signed URL lifetime, whether the reserved slot expires, and any size limits that change the part count.

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 primary action and return value, followed by the required next step and the disambiguating condition. Nothing is redundant with the name or annotations.

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 correctly supplies the return shape (object key plus signed URLs per part) and the downstream step, which is the critical missing piece an agent would otherwise lack. It would be complete with a note on slot/URL expiry before lunara_finish_upload is called.

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 all seven parameters are documented in-schema, including defaults for primaryLang/secondaryLang and the omit-to-reuse rule for projectId, so the description carries no burden here. It adds no parameter-level meaning beyond the flow, which is the baseline-3 case.

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 concrete operation (reserve an upload slot), the exact return payload (object key plus a signed URL per part), and scopes it with 'a file you hold locally', which separates it from the URL-based sibling lunara_subtitle_from_url. An agent knows what this does and what it produces 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?

Gives an explicit trigger condition ('file you hold locally') and the mandatory follow-up step ('After uploading the bytes call lunara_finish_upload'), which prevents a half-completed flow. It stops short of naming the alternative tool for remote files or stating what happens if the reserved slot is never finished.

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