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 and destructiveHint=false, and the description adds meaningful context beyond them: credentials are stored encrypted and never returned by any tool, and users can avoid passing secrets through chat by setting variables in the dashboard. It also signals non-idempotency by saying 'do this once per app,' consistent with idempotentHint=false. It does not spell out what happens if a duplicate project is created, which keeps it at 4 rather than 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 sentences that front-load the action and its required inputs before the sequencing instruction. Slight density from the embedded list of inputs, but no wasted prose.

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-parameter creation tool with a full schema and an output schema, the description covers the workflow-critical facts: required legal attestation, credential handling, and the mandatory follow-up call. Return values are covered by the output schema and the mention of 'the returned project id'.

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 thoroughly. The description reinforces intent for the required trio (target URL, login-success URL fragment, attestation, allowed hosts) but says nothing about the many optional presentation parameters (frame, voice, device, backdrop, language, app_locale), so it adds only modest value over the schema 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?

States a specific verb and resource ('Create a project') plus the domain object it encapsulates ('for one web app'), then enumerates the key inputs (target URL, login-success fragment, attestation, extra hosts, credentials). An agent can distinguish it from update_project or the guide tools 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?

Explicitly says 'Do this once per app; reuse the returned project id. Then call get_guide_instructions before writing the guides,' giving both cardinality guidance and the required next step in the workflow. This directly names a sibling tool and the condition that selects 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, idempotentHint and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: it returns a derived rate (credits per minute of video) and top-up links intended to be surfaced to the user, which shapes how the agent should present results. It does not mention freshness/staleness of the balance, which would be the last useful detail.

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 sentence with no filler, front-loading the balance and reserved credits before the actionable top-up links. Every clause earns its place by naming a distinct returned quantity.

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?

An output schema exists, so the description need not define return types, and it wisely focuses on the agent-facing workflow (surface links when short). Combined with annotations, an agent has enough to call it correctly and act on the result. The only gap is not explicitly stating the relationship to top_up.

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 clarify; baseline is 4. The description correctly spends its words on output semantics instead of inventing parameter guidance.

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 precisely enumerates what this tool returns (balance, reserved credits, available, rate, top-up links), which is a specific resource even without an explicit verb. It is distinguishable from siblings like top_up because it frames links as something to hand to the user rather than an action performed. It stops short of naming top_up as the alternative action, so differentiation is implied rather than stated.

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 context is implied by 'to hand to the user when the balance is short', which tells the agent what to do with the links but not explicitly when to call this tool versus top_up. There is no exclusion or prerequisite statement. An agent can infer the read-only check-then-top-up flow, but must do so itself.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so safety is covered; the description adds genuinely new behavior: variables surface as {NAME} placeholders and their values are never returned. That is exactly the kind of disclosure the agent cannot get from structured fields. It omits what happens when no guide of the requested kind exists.

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 what is returned, then how to select, then the caution. No filler and nothing repeated verbatim from annotations.

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

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

An output schema exists, so return-shape detail is unnecessary, and the description still covers the non-obvious return quirk (masked variables). Combined with the selector semantics and the read-before-edit rule, an agent has enough to call this 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 each parameter already carries a description, so the baseline is 3. The description usefully adds precedence between guide_id and kind and names the sibling tools that produce a guide_id, but it largely restates what the schema already says about kind and its default.

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 plus the exact payload returned ("its text, name and version"), which is concrete. It does not, however, distinguish itself from the similarly named sibling get_guide_instructions, leaving the agent to infer which one returns the saved document.

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 two explicit selection modes (pass guide_id for a specific guide, or kind for the newest of that kind) and a concrete precondition: "Read it before changing a guide you did not write." No exclusion against get_guide_instructions is offered, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. The description adds useful behavior beyond that by stating it costs nothing and should be called once before guide work.

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 and front-loads the core value: writing rules, effect choice, syntax, and examples. Every sentence adds useful information without 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?

Given the empty parameter schema, rich annotations, and an output schema, the description provides enough context for an agent to call it correctly. It covers what the tool provides, when to call it, and its cost profile.

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 there is no parameter semantics to document. The baseline for a parameterless tool is 4, and the description does not need to compensate for any schema gaps.

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

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

The description clearly states the resource: writing rules, effect selection, syntax, and examples for Screen Browser guides. It is specific, but it does not explicitly distinguish itself from sibling tools such as get_guide or validate_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?

It says to call this once before writing or editing a guide, giving a clear usage context. It does not name alternatives or when not to use it, but the triggering condition is explicit.

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

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

Annotations already declare readOnly, idempotent, closed-world, so the description's job is incremental and it delivers: signed URLs expire in ~15 minutes and must be re-fetched, and failures come back with an error plus hint. This expiry/caching trait is real context an agent cannot infer from annotations or 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?

One sentence, front-loaded with the returned state fields before the artifact URL caveat. The enumeration is long but each item is information-dense rather than 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?

Output schema exists, so return shape is largely covered, and annotations cover the safety profile; the description is still complete enough on the one behavior (URL expiry) that neither structured field captures. Missing only guidance about polling or behavior on nonexistent run_ids.

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?

A single parameter at 100% schema description coverage, and the schema already states provenance ('from start_run or list_runs'). The description adds no further semantics about run_id, 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 the resource (a run) and enumerates exactly what is returned — phase, finished flag, credits consumed, customer-visible activity, failure error with hint, and signed artifact URLs. An agent knows precisely what this call yields, though it never explicitly contrasts itself with list_runs 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?

Usage is implied rather than stated: the '(GET only, valid ~15 minutes; call again for fresh ones)' clause gives clear guidance for URL refreshes, but there is no when-to-use/when-not versus list_runs (bulk) or a polling cadence for in-progress runs.

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=false, so the safety profile is fully covered structurally. The description adds the notion of a login gate and host attestation flags, which hints at per-project state, but says nothing about ordering, pagination, or whether all projects or only accessible ones are returned.

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

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

Two sentences, zero waste: the first front-loads what is listed and its fields, the second gives the chaining instruction. Nothing is repeated or padded.

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 inputs, an output schema, and rich annotations, the only things an agent needs are purpose and how to use the result, both of which are present. Minor gap: it never mentions ordering or behaviour if the project list is large.

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 field enumeration adds a little context but no parameter semantics exist to document.

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 organisation's projects') and then enumerates the exact fields returned (id, name, target URL, login gate, guides, attestation). This clearly separates it from siblings like list_runs, list_voices, and create_project without needing to open 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?

'Use the id with the other tools' explicitly tells the agent how this tool feeds downstream calls, which is the key workflow context for a discovery/list tool. It stops short of stating when to prefer this over get_credits, list_runs, or update_project, but the resource distinction makes the alternatives 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=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?

Goes well beyond the annotations by disclosing that auth guides are never recorded and may use {USERNAME}/{PASSWORD} placeholders, that main guides become the video, and that saves create new versions rather than overwriting (relevant to the idempotentHint=false). It doesn't discuss permissions or failure behavior, but the added context is substantial.

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?

Dense but front-loaded: the core save action and versioning rules come first, prerequisites last. The conditional versioning clause is somewhat convoluted but every sentence carries 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 needn't be explained, and the description covers the meaningful gaps: versioning semantics, auth vs main behavior, prerequisites, and placeholders. An agent can call this correctly from the description alone.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds interpretation, notably that an unused name starts a new guide while a used one rolls into the newest guide, and that guide_id implies versioning. It repeats rather than extends the kind semantics already documented in the enum description.

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 ("Save a guide on a project") and immediately disambiguates the three save modes (new version by guide_id, new guide by unused name, new version of newest otherwise). This clearly separates it from siblings like get_guide and validate_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?

Explicitly names prerequisites and ordering: "Call get_guide_instructions before writing a guide and validate_guide before saving it." It also spells out the selection rule among the three save paths, leaving nothing 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?

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses the async lifecycle (poll get_run until is_terminal), the return value (run id), and the cost model (credits charged only when the video completes). The billing timing is exactly the kind of non-obvious consequence annotations cannot express.

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 dense sentences covering what, how, and the cost/return consequences, with the core action front-loaded and zero filler. Every clause carries actionable 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 non-idempotent, open-world mutation that starts an async job, the description covers the trigger, the polling requirement, the identifier returned, and when money is spent. With an output schema present, no further return-value explanation is required.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the guide_id default ("newest main guide") and that device selects desktop versus phone/tablet rendering. It does not touch frame, voice, language, or backdrop, but those are already well documented in 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 recording a video for a project") plus the two scoping choices that matter: which guide (newest vs. a specific guide_id) and which surface (desktop vs. phone/tablet device). An agent can distinguish this from create_project, put_guide, or get_run 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 the operational sequence explicitly: call this, then poll get_run until is_terminal. It is clear when to invoke it, though it does not name a when-not condition or contrast with a sibling (e.g., validate_guide as a pre-step) — that context is inferable but not stated.

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

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

Annotations already 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 that the mutation is non-destructive, idempotent, and closed-world. The description adds useful behavioral context beyond those annotations: only supplied fields are changed, and passing all three gate fields empty is refused. It omits auth requirements and return behavior, though an output schema exists.

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

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

It is front-loaded with the core action and uses only two sentences with no wasted framing. The trigger scenario and key constraint both earn their 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 complex 22-parameter mutation, the annotations, full schema, and output schema reduce what the description must carry. The description supplies purpose, a typical failure-driven use case, partial-update behavior, and a refusal constraint, though it highlights only a subset of the updatable fields rather than the full scope.

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% across all 22 parameters, so the schema already carries most parameter meaning. The description still adds a cross-field constraint not expressed in the schema: passing all three gate fields empty is refused, and it reinforces that the update is partial rather than replacement.

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, 'Change,' and resource, 'project,' then enumerates the kinds of settings being updated. It is clearly distinguishable from siblings such as create_project and list_projects because it focuses on modifying an existing project.

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 trigger scenario: typically after a run failed with login_failed and the login gate needs a selector or text instead of a URL fragment. It does not explicitly say when not to use this tool or name alternative tools, so it falls short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, and non-open-world, so safety is covered; the description adds genuinely new facts: the check costs nothing (relevant given get_credits/top_up siblings) and the response shape is problems with line numbers plus a corrected example and estimated video length. It stops short of detailing how many problems are returned or whether checks are fatal vs advisory.

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 core action and a compact list of checks, then response shape, then cost, then the prerequisite call. Dense but every clause carries information; the 'Costs nothing.' fragment is terse but 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?

With a full input schema and an output schema present, the description only needs to convey the checks performed and the workflow position, both of which it does. Minor remaining gap is guidance on whether a failing guide blocks saving or how to act on reported problems.

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 each parameter is already explained in the schema. The description only implies the role of `kind`/length via the 5-minute cap and does not add syntax or format detail beyond the schema's own text, 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 and resource ('Check a guide before saving it') and then enumerates exactly what is checked: unknown [DIRECTIVES], undefined {VARIABLES}, literal secrets, non-executable steps, missing "Go to" start, and length versus the 5-minute cap. This clearly separates it from put_guide (which saves) and get_guide (which retrieves) among the siblings.

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 usage unambiguously in the workflow: run before saving, and call get_guide_instructions before writing a guide. It names the prerequisite sibling but does not state any exclusion or failure case where validation should be skipped.

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