Screen Browser

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds the billing implication ('Nothing is charged for an incomplete run'), which is valuable behavioral information beyond annotations. No contradiction detected.

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

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

Two concise sentences with no filler. The primary action and condition are front-loaded, and the billing note adds value without redundancy. Every word 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 single-parameter cancellation tool, the description covers purpose, usage condition, and a key consequence (billing). With annotations covering destructive and idempotent behavior and an output schema present, 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?

Schema description coverage is 100%, and the parameter run_id is well documented in the schema. The tool description does not add additional parameter semantics, but since the schema fully covers it, the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Stop' and resource 'run', and explicitly restricts to queued or in-progress runs. This clearly distinguishes it from sibling tools like start_run, get_run, and list_runs, leaving no ambiguity about its function.

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 states when the tool applies (queued or in-progress runs), which provides clear usage context. It does not explicitly mention alternatives or exclusions, but the scope is obvious given the sibling set. Slight deduction for not naming alternatives, though the condition is clear.

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=false and destructiveHint=false, and the description's 'do this once per app' is consistent with non-idempotency. It adds that credentials are 'stored as encrypted variables' and that recording gates on login success, but says nothing about auth scopes, quotas, or what the returned id unlocks beyond reuse.

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 core action and ending with the persistence rule. The second sentence is long and packs five concepts into one clause chain, but nothing is redundant with the title.

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

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

For a 14-param creation tool with an output schema and full annotations, the description covers the workflow-critical concepts (login gate, legal attestation, extra hosts, encrypted credentials) and the reuse rule. The presentation defaults it omits are safely documented in the schema, so the gaps are minor.

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

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

Schema coverage is 100%, so the schema already documents all 14 parameters including enums and defaults. The description narrates only the salient subset (target_url, login gate, attestation, allow_hosts, variables) in prose; frame, voice, device, backdrop, language and app_locale are 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?

Opens with a specific verb+resource: 'Create a project for one web app', then enumerates the substantive content the project holds (target URL, login gate, attestation, hosts, credentials). It does not name update_project explicitly, but 'Do this once per app; reuse the returned project id' implicitly separates it from the update path.

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?

'Do this once per app; reuse the returned project id' gives real context on expected call frequency and post-creation behavior. There are no explicit exclusions or named alternatives, 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 and idempotentHint=true, so the description does not need to repeat safety. It adds value by indicating the tool reports the rate and top-up links, and suggests handing those to the user when balance is low. This is useful behavioral guidance but not extensive. No contradiction with annotations.

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

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

The description is a single sentence, free of filler, and front-loaded with the primary purpose. It packs several relevant details (balance, reserved, available, rate, top-up links) without excessive 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 zero-parameter tool with an output schema that presumably documents the return structure, the description is complete. It covers what the agent needs to know to call it and what to do with the results (hand top-up links to user). No gaps in calling or interpretation.

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

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

The tool has zero parameters, so there is nothing to document. The baseline for this case is 4, and the description adds no conflict. It focuses on output content rather than parameters, which is appropriate.

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

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

The description clearly states the resource (credits) and enumerates specific aspects (balance, reserved, available, rate, top-up links). It is distinct from sibling top_up, which is for adding credits, and from other tools like get_run or list_projects. The verb is implicit but the noun phrase is precise.

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 it is used to check credit-related information, and the mention of 'hand to the user when the balance is short' gives a usage cue. However, it does not explicitly contrast with alternatives like top_up or state when not to use this tool. Why an agent would choose this over other tools 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 annotations (readOnlyHint, idempotentHint), the description discloses that this is GET-only, that signed artifact URLs expire after ~15 minutes, and that fresh URLs require a subsequent call. This adds meaningful runtime behavior not captured by the schema or 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?

A single, dense sentence organizes status components as a list and tucks the expiration behavior into a parenthetical. Every word adds information and the key action is front-loaded. No redundancy or fluff.

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 read tool with an output schema, the description covers all essential runtime concerns: what data is returned, the read-only nature, and the temporary URL behavior. An agent can safely and correctly invoke it without additional documentation.

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 description contributes no additional run_id semantics beyond what the schema already states ('from start_run or list_runs'). Baseline 3 is appropriate because the schema fully carries parameter meaning.

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

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

The description begins 'Status of a run' which precisely states the resource (run) and the action (retrieve status). It enumerates specific status fields (phase, finish flag, credits, activity, error, signed URLs), making it immediately distinct from sibling tools like list_runs (all runs) or cancel_run (mutation).

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 clear usage: when you have a run_id and need its current status, call this tool. It adds that repeated calls are expected ('call again for fresh ones') but does not explicitly compare against siblings or state exclusions. Context is clear enough, but no alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds the scope ('organisation's projects') and field details, but does not disclose additional behavioral traits like pagination or auth requirements. This is acceptable but not exceptional given 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?

A single, front-loaded sentence states the action and resource, lists the output fields, and ends with a practical usage tip. Every word earns its place; 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?

With zero parameters and an output schema present, the description provides all necessary context: what is listed, what fields are returned, and how to use the result. Nothing essential is missing.

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

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

The tool has zero parameters, so the description has no parameter burden. Schema coverage is 100% and the empty input schema is unambiguous. Baseline 4 for zero-parameter tools 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 uses a specific verb ('List') and resource ('the organisation's projects'), and enumerates the exact fields returned (id, name, target URL, login gate, guides, attestation). This clearly distinguishes it from siblings like list_runs and list_voices.

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 explicitly tells the agent to use the returned id with other tools, which is clear usage guidance. It does not name alternatives or exclusions, but for a list operation with no sibling doing the same thing, this is sufficient.

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 idempotentHint=true, so safety is covered. The description adds useful behavioral context: results are ordered by recency, can be project-scoped or org-wide, and include a specific set of attributes. The output schema covers return shape, so no major behavioral gap remains.

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 compact sentence that front-loads the most important scoping information and then lists the returned attributes. Every part of the description 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?

Given no required parameters, a fully documented input schema, an output schema, and read-only/idempotent annotations, the description supplies the remaining essentials: ordering and optional scope. An agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and both parameters already have meaningful descriptions (limit range/default and project_id semantics). The tool description mainly reinforces the optional project scope without adding new parameter-level information, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('list') and resource ('runs'), and immediately anchors scope with 'organisation's most recent runs (optionally for one project)'. The field list distinguishes it from single-run tools like get_run and from mutation tools like cancel_run or start_run.

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?

Clear context is provided: the tool lists recent runs, optionally scoped to a project, and the schema adds 'omit for the whole organisation'. It does not explicitly say when not to use it versus siblings, but the resource and scope make the intended use fairly obvious.

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 and idempotentHint, covering the safety profile. The description adds filtering behavior (language code) and the format of custom ids, providing context beyond the annotations without contradiction.

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

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

Two concise sentences, front-loaded with the core purpose, then usage guidance. No wasted words, and the structure supports quick scanning.

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

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

For a simple list tool with an output schema and read-only annotations, the description covers purpose, filtering, and downstream usage. Nothing essential is missing for an agent 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% and the language parameter is fully described in the schema. The description reinforces the filtering behavior but does not add significant new meaning beyond what the schema already states, so a 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?

Description clearly states the tool lists narration languages and voices with tier and credits per minute, and mentions optional language filtering. This distinguishes it from sibling tools like list_projects or list_runs, and the verb 'list' is implied by the resource and behavior.

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 explicit guidance on using a voice id with create_project, update_project, or start_run, and notes custom:… ids for organisation voices. It does not explicitly contrast with alternatives, but there is no overlapping sibling tool for listing voices, so the context is sufficient.

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 mark readOnly=false, destructive=false, and idempotent=false; the description adds meaningful behavior beyond that: saving creates a new version, the auth flow is never recorded and may use credentials, and the main kind becomes the video. This gives the agent useful context about side effects and credential handling.

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 succinct sentences, each earning its place: purpose, kind semantics, and prerequisite. There is no filler or 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?

The description covers purpose, the auth/main distinction, and the validate_guide prerequisite; the input schema covers all parameter semantics at 100%, and an output schema exists, so return values need no description. It might have named project_id's source, but that is already in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the kind distinction already in the schema but introduces no new meaning for name, content, project_id, or video_title beyond their schema descriptions; therefore it stays at baseline.

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?

Description opens with a specific verb and resource: 'Save a guide on a project as a new version,' which clearly identifies the mutation and distinguishes it from read/list siblings like list_runs. It further clarifies the two kinds, so an agent can tell it apart from validate_guide 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?

It explicitly instructs 'Run validate_guide first,' which establishes the workflow context and the validation prerequisite. It does not enumerate alternative tools or state when not to use, but no sibling performs a guide save, so the 'Save a guide' statement plus validator prerequisite is clear context.

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

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

Goes well beyond annotations by disclosing that values are stored encrypted, never returned by any tool, pass through the conversation, and that existing variables not named are kept (merge semantics). These are non-obvious behavioral traits an agent needs to reason about safety and repeat invocations.

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 tightly written sentences, front-loaded with the core action, then security behavior, then merge behavior. No filler and every sentence carries distinct information.

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

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

With an output schema present, return values need not be explained, and the description covers the security and merge semantics an agent needs. Nothing essential is missing for correct 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%, so both parameters and the nested name/value objects are fully documented in the schema. The description adds the {NAME} reference convention but little else beyond what the schema already provides, 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 (Add or update) and resource (a project's variables), and clarifies what variables are (demo credentials and other values guides reference as {NAME}). An agent can easily distinguish this from siblings like update_project or put_guide.

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

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

Explains a meaningful usage consideration: credentials can be kept out of chat by setting them on the dashboard page instead. It gives clear context for when to use this tool, but does not name a sibling tool or a hard exclusion 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?

The description goes beyond annotations by revealing that the call shares the user's app page with Screen Browser, explicitly excludes credentials from evidence, and states that a reply comes on the run. It also clarifies side effects (nothing retried, guide unchanged). These are critical behavioral disclosures not covered by readOnlyHint/idempotentHint/destructiveHint. No contradiction.

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

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

Three sentences with no filler. The core action is front-loaded, followed by scope limitations and a critical user-consent warning. Every sentence adds value, and the structure leads with the most important information.

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

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

For a privacy-sensitive mutation tool, the description covers purpose, usage conditions, side effects, data-sensitivity, and the response location. An output schema exists, so return format need not be described. Nothing essential is missing for an agent to call this safely and correctly.

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

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

Schema description coverage is 100% and both parameters (run_id, note) are already well documented in the schema. The description does not add extra meaning about the parameters themselves; it focuses on the overall behavior. Baseline 3 is appropriate since 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?

States a specific verb ('Send'), a precise resource ('a failed run's evidence'), and the destination ('to Screen Browser'). It also explicitly scopes what it is not (no retry, no guide change), distinguishing it from other run-related tools. Clear and 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?

Gives explicit when-to-use ('Only for runs that failed on our side') and what it does not do (no retry, no guide change). Also adds a mandatory prerequisite ('Ask the user before calling') and a privacy caveat. It doesn't explicitly name alternative tools, but the schema for run_id references get_run, providing the needed context. Strong 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 indicate non-read-only and non-idempotent nature. The description adds crucial behavioral context: the run is asynchronous (you must poll get_run until is_terminal), credits are charged only on completion, and device selection constrains the output. It discloses the charging condition and the need for polling, which are not in annotations, making the side effects transparent.

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 compact: two sentences pack the purpose, the return value, the polling requirement, and the charging rule. It is front-loaded with the primary action, and every clause contributes new information. 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 tool with 7 parameters, an output schema, and complex side effects, the description covers all essential operational aspects: how to start, what to do with the returned id, device multiplicity, and when billing occurs. The existence of an output schema relieves the description from detailing return structure, and the description is complete enough for correct usage.

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 schema covers 100% of parameters with meaningful descriptions, so the baseline is 3. The description adds value by explaining relationships: the default guide is the newest, device variants (desktop/phone/tablet) and the rule that one run equals one device, plus how to handle multiple devices. This goes slightly beyond the schema's per-parameter explanations.

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

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

The description clearly states a specific verb ('Start recording') and a specific resource ('a video for a project'), and further specifies the object through guide_id and device. It differentiates from siblings by describing its role in the run lifecycle (creating a run, returning an id to poll) and mentions the asynchronous nature. This leaves no ambiguity about what the tool does.

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 provides direct usage guidance: it explains that one run per device must be started separately for desktop and phone versions, and instructs to poll get_run until is_terminal. It implies the context of starting a recording but does not explicitly state exclusions or alternative tools. The instruction on when to use (when you want to record) is implicit but clear enough.

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 mark this as read-only and idempotent. The description adds useful behavioral detail beyond that: the checkout link opens Stripe Checkout, requires no login, and the tool never charges anything itself. This helps an agent set user expectations correctly.

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 deliver all essential information with no filler. The main purpose is front-loaded, and the key caveat about not charging is stated directly.

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

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

For a single-optional-parameter tool with a rich schema and an output schema present, the description sufficiently explains what the tool returns, how to handle the response, and what side effects (none, besides opening Stripe) the user should expect.

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

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

The input schema already fully documents the single `pack` parameter, including enum values, credit amounts, prices, and default. The description adds only the general 'omit pack for suggested' behavior, which is already reflected in the schema's default note, so it provides marginal extra semantic value.

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

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

The description clearly identifies the tool's function: it returns links to buy more credits, including a Stripe Checkout link and the billing page. It is distinct from siblings like get_credits, which reads balance, and other run/project tools.

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

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

The description gives clear usage context: give the link to the user when they need to top up credits. It also clarifies that the tool itself never charges, and explains the default behavior when `pack` is omitted. It does not explicitly name alternatives, but no other sibling serves this top-up purpose.

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, destructiveHint=false. The description adds valuable behavior: only fields given are changed (partial update) and the refusal condition when all gate fields are empty. It does not disclose any side effects beyond that, but none are expected beyond the schema. This complements the annotations well without contradicting them.

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 action, then the typical use case, then a critical constraint. No wasted words. Every clause adds information that the agent needs, and the structure is easy to parse.

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 tool with 22 parameters and an output schema, the description does not need to enumerate every field; the schema covers that. It does mention the key gate constraint and the typical failure recovery context. It omits none of the essential call-time behavior or prerequisites beyond what the schema already states. A slightly higher score is withheld because it doesn't hint at any side effects on video or narration beyond what the parameters imply, but that's minor.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds cross-parameter meaning: it groups 'login gate' (three fields) and 'extra hosts' (allow_hosts) and clarifies that the gate fields cannot all be empty. This is beyond what the schema individually provides and helps understand the intent of those parameters.

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 verb ('Change'), a resource ('a project'), and a concrete list of what changes (login gate, extra hosts, target URL, name, narration, default device). It also gives a motivating scenario that distinguishes it from create_project and other tools. This is clear and 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 provides a strong usage context ('typically after a run failed with "Login gate failed"') and a constraint ('passing all three gate fields empty is refused'). It does not explicitly name an alternative tool, but the scenario effectively tells when to call this tool. No exclusions are given, but the guidance is adequate for an agent.

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 and idempotentHint, and the description adds significant context: it costs nothing, returns problems with line numbers, estimated video length, and credit cost. It also details the checks performed. No contradiction with annotations; adds substantial behavioral 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?

The description is a single paragraph with two sentences. It front-loads the purpose ('Check a guide before saving it') and packs the checks into a list. It's moderately concise but not overly verbose; every clause earns its place. Slightly longer than necessary but well structured.

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?

Given the tool's complexity, the existing output schema (which likely describes the returned problems and estimates), and the read-only annotations, the description covers all essential behavior: checks performed, return types (line numbers, length, cost), and the cost-free nature. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no parameter-specific meaning beyond what's in the schema; it discusses content checks but doesn't elaborate on how parameters influence behavior. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Check') and resource ('a guide'), and enumerates the exact validation checks (unknown DIRECTIVES, undefined VARIABLES, secrets, step executability, missing start, length cap). It clearly distinguishes from siblings like put_guide by positioning itself as a pre-save validation step.

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 'before saving it' gives a clear temporal context for when to use the tool. It implicitly contrasts with put_guide, but doesn't explicitly name alternatives or state when not to use it. The guidance is clear enough for an agent to infer the intended workflow.

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