Finishrecording

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

With no annotations, the description carries the full burden and does so unusually well: it discloses that the local file and share persist until FastFileLink reports a completed download, at which point the share stops and files are deleted — i.e. what gets destroyed and when. It also reveals a non-obvious behavioral quirk (google_drive delivery does NOT call Google, returning localPath plus uploadStatus pending instead), which an agent could not infer from any structured field. It adds prompt-level safety guidance against putting passwords, verification codes or key contents in summaryMarkdown.

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?

It is front-loaded with purpose and organized into short paragraphs per delivery mode, so it is scannable despite its length. A few lines are redundant: the ZIP paragraph restates the after_download cleanup behavior already explained two paragraphs earlier, and the closing instruction to put the returned url in the final answer is agent-facing output policy rather than tool documentation. Most sentences still earn their place because the branching logic is genuinely complex.

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 five-parameter mutation tool with no annotations, no schema descriptions and irreversible cleanup, the description is substantially complete: it covers defaults, file lifecycle, delivery routing, packaging, and failure messaging, and an output schema exists so return values need not be spelled out. The notable gaps are that recordingId semantics are absent and that cleanup manual is described as leaving the file in place without pointing at the cleanupRecording sibling that would later remove it. The relationship to abortRecording is likewise never stated.

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 supply the meaning, and it does for three of five parameters: it enumerates delivery values (ffl, local, google_drive), cleanup values (after_download, after_upload, manual), and package values (video, zip) with their behavioral consequences. summaryMarkdown gets partial treatment (used to build summary.md in the ZIP, must not contain secrets). recordingId — the one parameter that identifies the target and is nullable-with-null-default — is never explained, leaving the agent to guess whether null means the current active recording.

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 sentence gives a specific verb+resource pair — stop the recording and hand it to a transfer strategy — which is concrete enough to distinguish it from abortRecording (discard) and cleanupRecording (post-hoc deletion). It further clarifies scope by naming confirmUpload as a required follow-up for the google_drive path. It stops short of explicitly contrasting itself with abortRecording, which is the sibling an agent is most likely to confuse it with.

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 routes the agent across every meaningful branch: default ffl/after_download, local+manual for a returned file URI, google_drive+after_upload with an explicit two-step confirmUpload follow-up, and package=zip as the recommended Skill workflow versus package=video as the legacy default. It also states a hard constraint (ZIP packaging supports ffl delivery only) and tells the agent what to report on failure. This is explicit when-to-use guidance with named alternatives and exclusions.

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