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

Annotations establish this is a non-destructive, non-idempotent write. The description adds real behavioral value beyond them: timing is on the video clock, pauses are excluded, and markers surface via stop_recording as {atMs, label}. It omits failure modes (e.g., calling when no recording is running) and the 200-char 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?

A single dense sentence that front-loads the action and folds timing semantics and return-value behavior in without waste.

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 tool with no output schema, the description covers purpose, timing semantics, and where the result surfaces (stop_recording output), which is everything an agent needs 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 label is documented, but the description still adds meaning with concrete examples ("signed in", "error shown") that convey the expected brevity and granularity better than the schema's "in a few words."

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 plus resource: "Mark this moment of the running recording with a short label." It clearly differentiates from the recording-control siblings (start/pause/resume/stop_recording) by being an annotation action during an active recording.

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 "the running recording" implies it applies only while a recording is active, and the note that stop_recording returns markers clarifies downstream usage. It stops short of explicitly stating when not to use it or naming an alternative for post-hoc annotation.

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 (destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds substantial context beyond them: cursor movement, auto-scroll, a visible click highlight in the video, possible navigation side effects, and a named failure mode (ELEMENT_OBSCURED) that names the covering element. Only retry/timeout behavior is left unstated.

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, and the primary action is front-loaded ahead of side effects and error behavior. 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 discloses that it reports a started navigation, and it documents the main failure mode. It stops short of covering timing, retries, or what the navigation report actually contains, but is otherwise sufficient for a one-parameter click 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?

There is a single parameter with 100% schema description coverage; the schema already explains the ref format and its provenance. The description adds no ref-specific semantics, 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 (click) and resource (element), and the mechanism is fully spelled out: moves the visible cursor, scrolls into view if needed, and clicks. This is clearly distinguishable from siblings such as type, press, scroll, and navigate.

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 precondition (a ref from the latest snapshot, per the schema) and gives recovery guidance via ELEMENT_OBSCURED, but never states when to choose click over press, type, or navigate. Usage is implied rather than explicitly framed.

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, destructiveHint=false and openWorldHint=true; the description adds real context beyond that: the comment is public to anyone who can watch the video, a plan requirement exists, and a user-confirmation gate is mandated. It does not address duplicate posting or what is returned, but the key side-effect profile is disclosed.

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-loads the plan gate, then the action, then the safety workflow. The adjacent sentences about showing the user the change and passing the approved text are slightly redundant but each carries a distinct instruction, so there is little waste.

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 write tool with no output schema, the description covers access gating, visibility, confirmation, and the default target video. Only the response shape and duplicate-comment behavior are left unspecified, which is a minor gap.

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

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

Schema description coverage is 100%, and both parameters are documented there, including the videoId default. The description only restates the approved-text rule and the default recording, adding no new syntax or format meaning beyond 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 and resource: 'Post a comment on a video as the signed-in user.' This is clearly distinguishable from siblings like like_video, update_video, or get_video_activity, and the actor (signed-in user) is specified.

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 a concrete precondition ('Recordful Pro only') with the exact tool to check first (get_status recorder.account.plan) and an approval workflow before acting. It does not name sibling alternatives, but for a posting action the gating and confirmation rules are the useful 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 flag readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered in structured data. The description adds genuinely new behavior: an entitlement gate that must be verified through get_status and a mandatory user-confirmation step before mutation. It does not address duplicate-name handling or what is returned, which keeps it off 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?

Three short sentences, zero filler, with the entitlement check front-loaded before the action and the confirmation requirement last. Every clause carries an actionable constraint.

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 create tool with no output schema, the definition covers the plan gate and the confirmation protocol that an agent would otherwise get wrong. It is slightly thin on what a successful call returns (e.g. the new folder id) and on duplicate-name behavior, but nothing blocking 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 schema itself documents both `name` and `parentId`, including the 'Default: the top level' behavior. The description's 'at the top level or inside another folder' merely restates the parentId semantics already in the schema, so it adds no meaning beyond structured fields and 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?

The description gives a specific verb and resource ('Create a folder') plus the placement scope ('at the top level or inside another folder'), which separates it cleanly from list_folders and move_videos. It stops short of naming a sibling alternative explicitly, so it lands just under the top mark.

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 states a hard precondition ('Recordful Pro only (check get_status recorder.account.plan first)') and a required interaction protocol ('Show the user exactly what you will change and wait for their yes first'), which is exactly the when/when-not guidance an agent needs. Nothing about the decision to call this tool is left to inference.

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 destructiveHint=true, but the description adds what the annotations cannot: the deletion is permanent and irreversible, it also removes underlying files, it is plan-gated, and human confirmation is mandatory beforehand. That is materially more than the boolean flags convey.

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 plan gate, then the action, then the safety workflow. Nothing is wasted, and the most consequential constraint (irreversibility) appears before the call instructions.

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 destructive two-parameter tool with no output schema, the description covers everything needed to call it safely: access gating, the sibling tool to check first, permanence, and the confirmation sequence. No meaningful gap remains.

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 already documents both parameters; the baseline would be 3. The description adds genuine workflow meaning beyond the schema by specifying that confirmation must cover the exact video identified by title and link, and that videoId has no default for a delete.

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 ('Permanently delete a video and its files from recordful.app'), plus the scope of what is removed (the video and its files). An agent can immediately tell this apart from update_video or list_videos 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 precondition ('Recordful Pro only (check get_status recorder.account.plan first)') and names the sibling tool to call for that check. It also spells out the required workflow ordering: get user confirmation of the exact video, then call with confirm: true.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; "safe to call any time" largely restates it. The description does add genuine behavioral context by naming the recorder states (idle, starting, recording, paused) and the permission surface it inspects, which matters since there is no output schema to enumerate return values.

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 dense sentence front-loads the core answer (connected + what the recorder is doing) with no filler. The trailing "Safe to call any time" is slightly redundant with readOnlyHint=true, a minor cost.

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

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

With no parameters and no output schema, the description carries the return-value burden and does enumerate the reported fields and state values. It omits the shape of the response (nesting, how permissions are represented), which keeps it below a 5.

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. The sentence about what it inspects is not a parameter concern.

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 (report) and resource (recorder/extension status) and enumerates exactly what is reported: connection state, recorder state, mode, active tab, permissions. It is clearly distinct from the mutation siblings stop_recording, pause_recording, and resume_recording.

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?

"Safe to call any time" gives a clear condition for use with no exclusions needed for a read-only status check. It does not route the agent to related siblings such as probe_capture for permission probing or to start_recording for state transitions, so it stops 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=true, so the trailing 'Read-only' adds nothing; however, the description contributes real behavioral context the annotations lack: a plan-level gating rule and the prerequisite lookup that must precede a valid call. It does not mention failure modes or rate limits, keeping it below 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?

Three tight clauses with no padding. The plan constraint is front-loaded ahead of the capability statement, which is mildly backwards for an agent scanning for purpose first, 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?

With no output schema, the description carries the burden of describing returns and does so explicitly (bytes, percent, upload availability). Combined with the plan gate and prerequisite, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The prerequisite-check instruction effectively supplies the only 'input' that matters (the account plan).

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?

Concretely states the returned content: storage used in bytes and percent, plus whether more can be uploaded. The 'Recordful Pro only' gate and the mention of get_status as a prerequisite separate it from sibling tools like list_videos or get_video, though it never explicitly names an alternative it replaces.

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

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

Provides a clear precondition (Recordful Pro plan, verified via get_status recorder.account.plan first), which tells the agent both when the tool is valid and what to call beforehand. It stops short of explicit when-not-to-use guidance, e.g. what to do if the plan check fails.

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: it explains why readOnlyHint=false (it will start transcription as a side effect), that it waits by default even for an in-progress upload, and that the default target is the last recording. This reconciles the apparent tension between a "read" tool and a non-readOnly annotation, which is exactly the value the description should add.

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 plan gate and prerequisite, then the core action, then defaults. Sentences are dense but each carries information; minor redundancy is repeating the format enum already documented in 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?

Covers prerequisites, side effects, waiting semantics and defaults, which is most of what a five-parameter, no-required-param tool needs. With no output schema, it would benefit from one line on what comes back (plain text vs. VTT payload) and what happens if the plan check fails.

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

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

Schema coverage is 100% and the description largely restates the schema's format enum and the videoId default. It does add one genuinely new constraint — that a local-only recording must be uploaded before it can be referenced — but wait/start/timeoutMs behavior is left entirely to the schema. 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?

"Read back what was said in a Recordful video" names a specific verb and resource, and clearly distinguishes this from siblings like get_video, list_videos and get_status. It also states the plan scope (Recordful Pro only) up front, so an agent can tell immediately whether this tool applies.

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?

Strong routing context: check get_status recorder.account.plan first, and call upload_recording first if the recording exists only on this computer. What it lacks is an explicit negative case (e.g., when to prefer get_video or what to do if the plan check fails), so it lands 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=true and openWorldHint=true, so the safety profile is covered; the description adds real value by disclosing the polling semantics of 'wait' and the last-recording default, which are behavioral facts not in the annotations. It still omits what happens on a nonexistent or unauthorized videoId and whether polling keeps consuming quota, which the schema's timeout note only partially mitigates.

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, and the wait behavior plus default are front-loaded after the return-content summary. The opening is a field inventory in noun-phrase form rather than an action statement, which is slightly awkward as a lead.

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 only three parameters, the description carries the return-value burden and does so by naming the returned fields and the upload-stage state machine. Error behavior and the exact response shape remain undocumented, but nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description genuinely adds meaning: it defines the 'ready' state that the wait flag targets via the uploading → processing → ready progression, and restates the last-recording default for videoId. The timeout parameter's retry-again behavior is left entirely to the schema, which is acceptable given full coverage.

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

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

The description names the resource concretely and enumerates exactly what a single Recordful video record yields (title, length, viewership, view/edit links, upload stage), which distinguishes it from list_videos and get_transcript. It never states an explicit verb like 'fetch' or 'retrieve', relying on the name and title to supply that, so it is clear but not fully self-contained.

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?

'With wait, keeps checking until it's ready' and 'Defaults to the last recording' give concrete operational context for the common calling patterns. However, there is no guidance on when to choose this over siblings such as list_videos, get_transcript, or get_video_activity, and no statement of preconditions (e.g., that the video must exist or belong to you).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description still adds real value by restating read-only in context and by disclosing the plan gate and the pre-check call. It also discloses result ordering ('oldest first') and that comments carry author and time, which the annotations do not convey. It omits pagination or volume limits for comment lists, which is the main remaining behavioral 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 compact sentences, each with a distinct job: eligibility gate, payload contents, default. The plan restriction is front-loaded where an agent will see it before calling, and there is no redundant 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?

For a one-optional-parameter read tool with no output schema, the description usefully enumerates the return payload (views, likes, comments with author and time) and its ordering, which is exactly what an agent needs in place of an output schema. It lacks only comment-list volume or pagination behavior and any explicit contrast with get_video.

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 videoId parameter is already documented, including its pattern source and default. The description's 'Defaults to the last recording' merely echoes the schema rather than adding format or resolution detail. Baseline 3 applies when the schema carries the parameter burden.

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 names a specific resource and its contents: 'What viewers did with a video: its view count, likes, and every comment (oldest first, with author and time).' That is far more precise than the title, and it implicitly separates this read-aggregation tool from write siblings like like_video and comment_on_video. It stops short of naming a specific sibling it should be preferred over, such as get_video or get_transcript, so it is clear but not fully differentiated.

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 one concrete precondition, 'Recordful Pro only (check get_status recorder.account.plan first)', which is genuinely actionable routing guidance. It also states the default behavior when no ID is passed. However, it never says when to call this instead of get_video, list_videos, or get_transcript, so the alternative selection is left to inference.

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

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

Beyond the annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description discloses the Pro-plan entitlement gate, that the call can remove an existing like, and that it returns the new like count. Idempotency is consistent with the annotations. It stops short of describing failure behavior when the plan check fails or the video ID is invalid.

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

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

Four short, purposeful sentences with the entitlement constraint front-loaded, then the effect, then the return value, then the target default. No filler and no repetition that isn't doing work.

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-optional-parameter mutation with no output schema, the description covers the plan gate, side effect, return value, and default target. The remaining gap is error/entitlement failure behavior, which is minor given how simple the tool is.

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 both parameters are already documented, including the liked toggle and the videoId source list. The description restates the liked:false semantics and the last-recording default rather than adding new meaning, 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 verb and resource — 'Like a video as the signed-in user' — and immediately clarifies the inverse behavior ('liked: false removes it'). This is easily distinguished from nearby siblings like comment_on_video or update_video, which do not affect like 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?

It gives both a hard prerequisite ('Recordful Pro only (check get_status recorder.account.plan first)') and a default-resolution rule ('Defaults to the last recording'). It does not name alternatives or when-not-to-use cases, but the plan gate and implicit-target rule cover the main usage decisions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely new behavior — a paid-plan entitlement and the required pre-check via get_status. It stops short of disclosing ordering, pagination, or whether shared/inherited folders are included, which matters for a list tool with no output schema.

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

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

Three short sentences, front-loaded with the blocking prerequisite, then the resource, then the cross-reference to list_videos. The parenthetical plan-check is slightly dense but each clause carries information; 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 correctly spends its words on the returned fields and the null-parent convention, plus the plan gate. Missing only ordering/pagination and whether the result is flat or a tree, which would matter for an agent building a hierarchy from parentId.

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 baseline is 4 and there is no parameter meaning the description could add. Instead it usefully documents the response shape (parentId null at top level), which compensates for the absent output 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 and resource ('The user's folders on recordful.app') and enumerates the returned fields (folderId, name, parentId, shared), so the agent knows exactly what it gets. It also scopes the data to the user's own folders rather than a workspace-wide set, which is the kind of distinction that separates it from list_recordings/list_videos.

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 a clear prerequisite gate: 'Recordful Pro only (check get_status recorder.account.plan first)', which tells the agent to verify the plan before calling. It also points to list_videos for per-video folder association, but does not say when to prefer create_folder or move_videos, nor any when-not condition.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds genuinely new behavior: results are newest-first and each entry carries size and an optional videoId meaning 'already uploaded', which tells the agent how to interpret missing values. Minor gaps remain (empty state, whether any cap on count exists), 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, front-loaded with the scope and ordering constraint, then the alternative route. Every clause carries information an agent would otherwise have to guess.

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, and the description compensates by enumerating the returned fields and the semantics of the optional videoId. Combined with the annotation-covered safety profile and the explicit sibling routing, nothing needed to call or interpret this tool 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 the baseline is 4 and there is no parameter meaning to supply. The description correctly spends its space on scope and return fields rather than inventing arguments.

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 ('List the recordings saved on this computer') plus the ordering ('newest first') and the shape of each item (takeId, size, timestamp, videoId). It explicitly contrasts itself with list_videos for cloud recordings, so an agent can separate it from the sibling without opening a 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?

Provides an explicit when-not and a named alternative: recordings made while signed in to Recordful Pro go to the cloud instead, and the agent is routed to list_videos. That is the exact routing decision an agent needs for a local-vs-cloud listing choice.

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?

Although annotations already mark the tool as read-only, the description is valuable because it explicitly lists the fields (e.g., videoId, date, length) that will be returned in the response. This is a key behavioral detail missing from the structured schema.

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

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

The definition is highly concise, presenting all necessary information in a single, well-structured sentence without any superfluous words.

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?

It specifies the sorting logic (newest first) and the fields contained in each result, which is crucial given that a full output schema is not provided. It is a strong definition despite the lack of a return 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%, so the description doesn't need to compensate for gaps. It is concise but does not add significant semantic meaning beyond what the parameters already state.

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 explicitly defines the resource (user's videos), the action (list), and the domain (recordful.app). It clearly distinguishes itself from single-item retrieval functions like get_video.

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 identifies filtering by title as an optional feature, which helps clarify usage. However, it does not advise when to use this tool versus other list-related siblings, nor does it define complex use cases.

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

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

Beyond the annotations, it discloses a significant side effect the agent could not otherwise know: moving into a shared folder shares the videos, except private ones. It also explains partial-failure behavior (unmanageable videos come back as skipped) and imposes a human-confirmation gate before mutation. This is exactly the kind of consequence disclosure the 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?

Four tight sentences, front-loaded with the plan gate before the action, and every clause carries information (gating, destination, side effect, confirmation, partial failure). The parenthetical and exception clause make it slightly dense 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?

There is no output schema, and the description partially compensates by describing the skipped-videos return behavior. Combined with the plan gate, sharing side effect, and confirmation flow, an agent has enough to call this correctly, though a fuller picture of the success response shape is absent.

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

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

Schema coverage is 100% and both parameters are already documented, including that folderId null means top level. The description restates the null-to-top-level behavior but adds no new syntax, constraints, or semantics. Baseline 3 is appropriate when the schema does the 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 names a concrete verb and resource ("Move videos into a folder") and clarifies the destination semantics including the null/top-level case. It does not explicitly contrast itself with siblings like update_video, so an agent must infer that metadata changes belong elsewhere, but the operation itself is unambiguous.

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 a hard prerequisite (Recordful Pro only, check get_status recorder.account.plan first) and an explicit interaction requirement (show the user the exact change and wait for confirmation). It also carves out an exception case (private videos are not shared). What's missing is naming an alternative tool for related-but-different operations.

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 useful context beyond annotations — namely that it waits for load, returns the final URL and title (important after redirects), and that prior snapshot refs are invalidated ('Refs from earlier snapshots stop working'). That last point is a real consequence an agent needs. However, it doesn't mention that this is a state-changing navigation (readOnlyHint=false) that could trigger page-level side effects, or any auth/rate considerations. Reasonable but not rich.

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 scope, then the return value, then the caveat about snapshot refs. Every sentence earns its place with 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?

Covers the key facts an agent needs: it's an http(s) navigation in the recorded tab, it waits for load, what it returns, and that snapshot refs are invalidated. No output schema exists, and the description compensates by naming the return values. Could be slightly stronger on when navigation alone is sufficient versus when a wait_for is needed, but it's solid.

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% — both url and timeoutMs are fully described in the schema, including maxLength, min/max bounds, and default. The description adds nothing about parameters beyond what the schema provides, which is the baseline 3 when the schema does the heavy lifting.

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 ('Open') and resource ('http(s) URL'), plus the critical scoping detail that it happens 'in the tab the user handed to Recordful'. This distinguishes it clearly from siblings like click, snapshot, or get_status, which operate on an already-loaded page.

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?

Positions the tool implicitly as the entry point to a browsing session — you navigate before you snapshot, click, or type. It doesn't explicitly say 'use this first' or name alternatives for loading content, but the workflow context is clear enough for an agent to place it correctly among the recording/browsing 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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description's 'No-op if already paused' largely restates the idempotency hint, and it omits behavior such as what happens if no recording is active or what state changes occur internally.

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, followed by usage guidance and an important edge-case note. No filler or redundancy.

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

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

For a no-parameter tool with annotations covering safety and idempotency, the description is nearly complete. It is slightly light on edge behavior when no recording is in progress, which would help an agent know whether a call is meaningful.

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 are zero parameters, so the baseline is 4. The description adds no parameter semantics, but none are needed for this tool.

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: 'Pause the current recording.' The action is unambiguous and naturally distinguished from resume/stop/start siblings, 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?

It gives a concrete when-to-use scenario ('while you plan the next step so the video has no dead air'), which is clear context. It does not, however, name alternatives like stop_recording or resume_recording or state when not to use it.

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 non-readonly, non-idempotent, open-world behavior, so the safety bar is partly covered. The description adds genuinely useful disclosure beyond that: the key press triggers the page's real effect (submitting, moving focus, deleting) because synthetic keys are otherwise ignored, which explains the non-idempotent side effects and warns of consequential actions.

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 capability and its examples are front-loaded in the first sentence, with the behavioral caveat following. It is dense but every clause carries information; only the double-embedding of examples and the parenthetical aside slightly dilute readability.

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

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

For a single-parameter tool with no output schema and rich annotations, the description covers purpose, valid inputs, and side-effect behavior. It omits edge cases such as pressing keys with no focused element or a missing target, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and the schema already enumerates valid keys, modifiers, and the regex pattern. The description's examples mirror that content rather than adding new semantics (e.g., no guidance on focus requirements, timing, or what happens when no element is focused), 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 and resource ("Press a key in the focused element") and immediately grounds it in recognizable scenarios (submit, move focus, close dialog, menu navigation). It is trivially distinguishable from siblings like click, type, and scroll, which operate on different targets.

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 examples effectively communicate when to reach for this tool rather than type or click, and the modifier syntax (Shift+Tab, Control+a) tells the agent what shapes of input are expected. There is no explicit statement of when NOT to use it or a named alternative, so it stops 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 only declare readOnlyHint=true and openWorldHint=false, so the description adds real value: it states the operation is non-recording, requires no user click, and is refused during an active recording. That refusal constraint is meaningful behavioral context an agent would otherwise miss.

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 dense sentence front-loaded with 'Diagnostic:' and with no wasted clauses — each sub-clause (no user click, permission scope, recording refusal) earns its place.

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

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

For a read-only, single-optional-param diagnostic with no output schema, the description conveys what the check evaluates (capture feasibility and permission grants). It stops short of describing the return shape, but the tool is simple enough that this is a minor gap.

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

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

Only one parameter, tabId, and schema description coverage is 100% with the default behavior (active tab of last focused window) fully documented in the schema. The description adds nothing beyond the schema, 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?

Names a specific verb (check) and a precise resource (whether the extension can capture the target tab without a user click, plus which optional Chrome permissions are granted). This clearly distinguishes it from siblings like get_status, screenshot, or start_recording.

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 'Refuses while a recording is running' clause is an explicit when-not condition, telling the agent this is a pre-recording diagnostic. It doesn't name an alternative tool for the same check, but the context is well established.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The no-op clause adds a concrete edge-case behavior (wrong-state calls neither error nor mutate), which is useful but closely overlaps the idempotent hint; nothing is said about permissions or the resulting recording state.

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, with the action first and the edge-case caveat second. Every clause earns its place.

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

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

For a no-parameter, no-output-schema control tool with annotations covering safety, the description supplies what an agent needs to call it correctly. It is slightly thin on what state the recorder is left in after the call, but 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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool 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 ("Resume a paused recording") and the word "paused" implicitly distinguishes it from the sibling start_recording, which begins a new capture. An agent can pick the right tool 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?

"No-op if not paused" gives a clear usage condition and tells the agent it is safe to call opportunistically without checking state first. It stops short of explicitly naming the alternatives (pause_recording/stop_recording) or stating exclusions, so it is strong context rather than 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 declare readOnlyHint and openWorldHint, so the safety profile is already covered. The description adds a real operational precondition not present in the annotations: the tab must be the active tab of its window, plus the 'right now' timing semantics that imply a live capture. It does not describe return format, but no output schema is needed for an image.

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, with the core action and its purpose front-loaded and the precondition placed second. Every clause earns its place.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies purpose plus the one precondition an agent must satisfy. It stops short of relating itself to the surrounding flow (navigate, wait_for, snapshot), but nothing critical to invoking it 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, which is the baseline-4 case. There is nothing parameter-wise the description needs to compensate for, and it correctly avoids inventing arguments.

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 (capture) and resource (what the recorded tab shows now) plus the output form (as an image), so the agent knows this returns a picture rather than data. It does not explicitly differentiate itself from the similarly named sibling 'snapshot' or 'probe_capture', leaving a small ambiguity about which one produces an image.

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?

'to check the page looks right' implies a verification use case, which is decent context. However, it never tells the agent when to prefer this over siblings like snapshot or probe_capture, nor when not to use it.

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, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds the genuinely useful behavioral detail that scrolling is smooth and that amount defaults to most of a screen, but says nothing about the viewport change affecting later screenshot/snapshot output or about any side effects.

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 covers the verb, both modes, and the default magnitude with no filler. The phrasing 'by amount pixels' is slightly awkward but costs nothing in length.

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-param, no-output-schema tool the description covers both modes and the amount default adequately for correct invocation. It omits where refs originate (presumably the sibling snapshot tool), a minor but real gap for an agent that has not yet captured one.

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 ref, amount and direction are already documented, including the default and the enum. The description restates the same facts ('by amount pixels or most of a screen') without adding format, range, or interaction detail beyond the schema, 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 specific verb (scroll) plus resource (page/element) and decomposes the tool into its two operating modes: bring a ref into view, or scroll the page in a direction. The scope is unambiguous, though it never names or distinguishes itself from siblings like navigate or snapshot.

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?

"Either bring an element (ref) into view, or scroll the page in a direction" explicitly frames the two mutually exclusive usage modes and which parameter selects which. It gives no exclusions, prerequisites, or named alternative tools, so it stops 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context beyond them: refs persist while an element remains on the page, which explains the non-idempotent listing behavior flagged by idempotentHint=false. It does not mention limits or truncation on very large pages.

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: the first leads with what is listed and what each entry contains; the second carries the ref-stability caveat. Every clause earns its place with no redundancy.

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

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

There is no output schema, so the description correctly carries the full burden of describing the return shape (ref, role, accessible name, value/state, bounding box in CSS pixels). It omits the 'scope' parameter and any behavior for very large pages, but is otherwise complete for a single-optional-param read 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 'scope' enum is fully documented in the schema itself (page vs viewport). The description adds no information about the parameter, 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 ('list') and resource ('interactive elements ... and headings in the recorded tab'), and enumerates the element kinds and the exact fields returned. An agent can distinguish it from screenshot (visual capture) and from click/type (which consume the refs this tool emits).

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 'each with a ref to pass to click/type/scroll/wait_for' makes the workflow role explicit: call this to obtain refs for the interaction tools. However, it never states when NOT to use it (e.g. versus screenshot for visual inspection) or any prerequisite about recording state.

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

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

Beyond the annotations, it discloses meaningful behavior: settings are pulled from the user's saved Recordful config (mode, microphone, camera, countdown), that the promise resolves once capture is actually live, and that it reports failure reasons. Annotations only carry safety hints, so this additional state-machine context is genuinely valuable; it stops short of 5 only because it doesn't mention permissions or rate/side-effect details.

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 resource, followed by resolution semantics and the sequencing precondition. Every sentence earns its place with 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?

For a no-required-parameter action tool with full schema coverage and safety annotations, the description covers what it does, what config it applies, how it resolves, and when to call it. It could be more complete by noting what happens on an already-recording tab or linkage to pause/stop, but it is essentially sufficient to invoke 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 both parameters (tabId, timeoutMs) are fully documented in the schema, making the baseline 3 appropriate. The description adds only indirect context (settings come from saved config) without clarifying parameter behavior beyond 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 and resource ('Start a Recordful recording on the target tab') and distinguishes itself from siblings by naming the state transition it performs versus stop_recording/pause_recording/resume_recording. An agent can route to the correct tool from the description alone.

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 a clear prerequisite/precondition for success ('Navigate to the page you want to show before calling this'), which explains when and how to sequence this against the navigate sibling. It does not explicitly name when not to use it or point to alternatives, so it stops short of 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?

The description adds substantial behavior beyond the annotations: it opens the editor, explains that cloud recordings are already uploading with videoId and links, and local recordings are saved as takeId for later upload. It also notes that placed markers are returned, giving an agent useful side-effect and return-shape 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?

The description is front-loaded with the action and then explains the immediate consequence and return structure. It is dense but every sentence earns its place, especially because no output schema is provided.

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 stop action with no output schema, the description covers what happens, where the recording goes, and the follow-up for local recordings. The remaining timeout details are handled 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 coverage is 100%, so timeoutMs is already fully documented in the input schema. The description does not add meaning to the timeout parameter, focusing instead on return values and side effects.

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: stop the current Recordful recording. It also places the action in the sibling lifecycle by distinguishing stop from start/pause/resume, and names upload_recording for the local case.

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 usage context is clear: call it when the current recording should end, and Recordful will open its editor just like clicking Stop. It names upload_recording as the follow-up for local recordings, but it does not explicitly state when not to use this tool or discuss timeout behavior.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds behavior not in the structured data: that a click is performed first, that typing occurs at a human pace, and that without 'clear' text is appended rather than replacing. It does not disclose failure modes or what happens with an invalid ref.

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, then the replace option, then the alternative tool. Every sentence carries distinct information with no repetition.

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 4-parameter interaction tool with full schema coverage and annotations, the description covers purpose, target element types, key parameter intent, and the sibling alternative. Only error/edge-case behavior (stale ref, non-editable element) is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents ref, text, clear, and delayMs with defaults and bounds. The description only echoes the 'clear' semantics ('replace what is already there') and adds nothing about ref or delayMs, 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 ('Click the field, then type the text') and scopes the supported targets (text inputs, text areas, content-editable areas). It is clearly distinguishable from the sibling 'press', which it explicitly names as the tool for non-text keys.

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 routing rule: 'Use press for Enter, Tab and other keys', which tells the agent when to pick the alternative. It also explains the 'clear' choice for replacing existing content. It lacks guidance on failure/edge cases (e.g. stale refs) or when to prefer click/scroll 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?

Annotations only say it is a non-destructive, idempotent, open-world write. The description layers on plan gating, a mandatory human-confirmation step, the permission model (recorder or workspace owner), and the default target (last recording) — none of which appear in the annotations.

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

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

Front-loaded with the plan gate and confirmation protocol, which are the highest-value facts. Some space is spent re-enumerating the three visibility values that the enum schema already documents, which is the only real redundancy.

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

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

For a 3-parameter mutation tool with no output schema, the definition covers everything an agent needs to call it safely: entitlement check, permission requirement, confirmation gate, default video target, and allowed values. No behavioral gap remains that would cause a bad invocation.

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

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

Schema coverage is 100% and the description's visibility definitions and "defaults to the last recording" note restate the schema's own property descriptions nearly verbatim. It adds no syntax, validation, or edge-case meaning beyond the schema, 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 and resource ("Change a video's title and/or who may watch it") and enumerates the exact mutable fields. It is clearly distinguishable from siblings like delete_video, move_videos, and get_video, which touch the same resource but do different things.

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 the gating prerequisite (Recordful Pro, verify via get_status recorder.account.plan), the required confirmation flow ("Show the user exactly what you will change and wait for their yes first"), and the authorization rule. An agent knows exactly when it may and may not call this.

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 only say this is a non-destructive, open-world write. The description adds the behavior that matters: it blocks until the upload finishes by default, and a cloud-originated recording is a no-op that just returns the existing asset. It does not mention failure modes such as expired plan mid-upload or permission errors, so it stops short of full disclosure.

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?

Five short sentences, front-loaded with the plan gate and the core action, then returns and the next step. The parenthetical plan check and the closing sentence about cloud recordings both earn their place, though the density of defaults in one paragraph makes it slightly harder to scan.

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 states what comes back (videoId plus view and edit links), covers the plan prerequisite, the blocking default, and the cloud-recording edge case. An agent has everything needed to decide whether to call it and what to do with the 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 coverage is already 100%, so the baseline is 3, but the description still contributes: it foregrounds the default wait behavior, the default-to-last-recording selection, and the timeout retry loop rather than leaving the agent to scan the schema. It does not explain the interaction between force and idempotentHint, which is the one parameter subtlety 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?

States a specific verb and resource ("Upload a local recording to recordful.app") and immediately distinguishes the two cases an agent will hit: a local recording gets uploaded, while a cloud recording is already uploading and is simply returned. That separation from siblings like start_recording or list_recordings is explicit rather than inferred.

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 a concrete precondition ("Recordful Pro only (check get_status recorder.account.plan first)") and names the follow-up step (get_transcript reads it back). It lacks an explicit when-not-to-use statement or direct naming of an alternative upload path, which keeps 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 cover the safety profile (readOnly, non-destructive, openWorld, non-idempotent), and the description adds genuinely useful behavior: it keeps waiting across navigations and fails with WAIT_TIMEOUT rather than hanging. It stops short of describing what a successful wait returns, though no output schema exists to cover that.

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, front-loaded with the primary success condition and followed by the failure mode. Every clause carries information; nothing is padding.

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 four-parameter, no-output-schema wait tool, the description covers the core trigger conditions, the hidden-state variant, cross-navigation persistence, and the timeout failure. The only gap is return value on success, which is minor for a blocking primitive.

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% — text vs ref exclusivity, case-insensitive matching, the state enum, and the timeout default/range are all documented in the schema. The description restates the state semantics but adds no syntax or format detail beyond it, 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 (wait) and the two triggering resources (text on page, element ref), plus the inverse mode (state "hidden"). Nothing in the sibling list does the same thing, so an agent can route to it unambiguously.

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 the description — you call it when you need to block until content appears or disappears — but there is no explicit when-to-use versus siblings like snapshot or get_status, and no stated preconditions or exclusions.

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