Bowmark

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

With annotations already covering safety traits, the description adds substantial behavioral context: the return value is a single-use expiring URL, the user signs in on that page, wait_for_sign_in completes the flow, failures return a list of supported sites, and re-signing in targets the same connection id.

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 purpose and trigger are front-loaded, and the multi-paragraph structure follows the workflow logically. It is longer than necessary but most sentences carry actionable detail for a complex sign-in flow.

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 must explain return values; it does so with url and expiresAt. It also covers failure behavior, the next step with wait_for_sign_in, and the saved-login case, which is complete for this 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 coverage is 100%, so the baseline is 3. The description adds meaning by explaining the connection parameter’s use case: signing back in to a saved login that stopped working, with the fresh session going into the same id.

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: get a sign-in link for one site. It distinguishes this tool from sibling tools by explaining that wait_for_sign_in is called afterward and that the user should not be sent to the extension or dashboard.

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

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

It gives explicit triggers: call whenever the user asks to log in, sign in, connect, or link an account on a site. It also states when not to use it, names the follow-up tool, handles the saved-login case, and explains failure 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 only say readOnly/idempotent/non-destructive; the description adds the crucial two-step semantics that annotations cannot express — it deletes nothing itself, a human must confirm on the dashboard, the returned `confirmUrl` is the only path to completion, and no call can finish it programmatically. It also flags irreversibility, which reconciles the surprising destructiveHint=false.

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 most decision-relevant fact ("This does not delete anything by itself") before anything else, and every following sentence carries a distinct load: the confirmation flow, the return value, the trigger condition, and two exclusion rules. 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 one-parameter mutation-initiation tool with no output schema, the description supplies everything needed: the return value (`confirmUrl`), what the user must do with it, the irreversibility, and the routing rules against siblings. Nothing an agent needs 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 description coverage is 100% and the schema already documents that `id` is the connection id from `list_connections`, so the description largely restates it. The single-parameter baseline of 3 is appropriate; no format or edge-case guidance is added beyond the source 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?

States a precise verb and resource ("Start deleting a saved login") plus the identifier source, and explicitly distinguishes itself from siblings `list_connections` (source of the id) and `logout_connection` (the sign-out alternative). An agent can tell exactly what this does and does not do 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?

Gives an explicit when-to-use condition ("Only call this when the user asked to remove a saved login"), names the alternative for a different intent (`logout_connection` for signing out), and states a negative case ("Never call it to 'fix' a connection that is merely stale") with the reasoning that `needs_reauth`/`expired` self-heal via sign-in.

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, destructiveHint=false and openWorldHint=false, and the description is consistent with all three ('One read-only call, no site is touched'). Beyond that it discloses real behavioral quirks the annotations cannot: a non-matching query says so rather than erroring, answers can be sliced (so absence from a sliced list means nothing), and the index vs. detail levels behave differently. That is exactly the added context the dimension rewards.

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 primary trigger and organized with bold sub-headings, and the closing loop ('call get_library -> write a JS script -> send it to run') is a useful anchor. It is long for a two-parameter lookup and repeats the hostname guidance already present in the schema, so not every sentence strictly 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?

There is no output schema, so the description must explain returns — and it does: the function library with capabilities that fan out across sites, plus site-specific providers when a company was named, and the index/detail distinction. Combined with the error and slicing behavior, an agent has everything needed to call this correctly and interpret the answer.

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, but the description adds meaning beyond the schema: the hostname rule (only a hostname settles coverage; strip URL path/params) and the batching semantics for `queries` (one per part, max 6, `query` folded in). Some of this is duplicated verbatim in the schema descriptions, which caps the score.

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 concrete job — it 'answers whether Bowmark can already DO the thing' and returns 'the function library you write against' with named capabilities like `bowmark.flights.search(...)`. It also separates itself from siblings by naming the `run` tool and the get_library -> script -> run loop. The opening line, however, leads with usage ('Use this whenever a task touches a live website') rather than what the tool returns, so the actual purpose only surfaces in the fourth paragraph.

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?

Explicit when-to-use is given twice (live-website tasks, and questions about how to write/run a Bowmark script), plus an explicit narrowing condition — 'Behind a LOGIN is narrower' and it works only where a purpose-built provider or saved connection exists. It also justifies the call ('checking is cheap') and states the fallback ('you can use your normal approach'), 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?

Annotations already mark the tool as read-only, and the description adds meaningful behavioral detail: it returns only a URL, opening it requires the user to be signed in and confirm identity, and only the user's own browser can read the resolved value. This is security-relevant context beyond what readOnlyHint provides.

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 two sentences with no filler. The first sentence states the function and a concrete use case; the second adds the critical return-type and security behavior. Every sentence 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 one-parameter, read-only tool with strong annotations, the description fully covers what the tool returns, the authentication requirement, and the user-specific access model. Since there is no output schema, the explicit statement that it returns a URL is valuable and sufficient for an agent to invoke and interpret 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 description coverage is 100%, so the single `name` parameter is already documented as the secret's name as shown by list_secrets. The description adds only a mild constraint ('one stored secret this account holds') but no new format or validation detail, which matches the baseline of 3 for high schema 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 states a specific verb and resource: return the dashboard link for one stored secret. It also distinguishes itself from value-returning siblings by explicitly promising 'a URL, never a value,' so an agent can tell it apart from tools like request_secret or list_secrets.

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 context: use this when the user wants a navigable link to one of their stored secrets, such as answering 'where is my Acme password?' with somewhere to go. It does not explicitly name alternatives or say 'not when the secret value itself is needed,' so it stops short of a 5, but the URL-versus-value contrast provides 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?

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false): the price is charged up front and is non-refundable, a live price above the agreed amount is refused before any charge, and repeating the same call cannot buy twice. This is exactly the money-and-side-effect context an agent needs and that the schema/annotations do not 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?

Front-loads the no-argument first call, then the pricing/confirmation contract, with the critical 'Never buy without asking' bolded. It is long, but for a tool that spends money every sentence is load-bearing; only the introductory explanation of what a dedicated IP is could be trimmed.

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 still names the return fields (`priceCents`, `message`, `mustFirst`) and the full confirm-before-charge loop, including the prerequisite path. Nothing an agent needs to call this safely 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 baseline is 3, but the description adds real workflow meaning: `confirmPriceCents` is the agreed price from the unconfirmed call and is the only thing that buys, `another` is only for a user-requested second IP, and `country`/`termDays` defaults (US, 30) are restated in context of the pricing flow.

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 action (lease/buy a dedicated IP) and explains exactly why it exists: sites like LinkedIn that only accept a login from the original address. It routes to the sibling `get_library` for locating such sites, so an agent can distinguish this from the other connection/secret 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?

Explicit sequencing: 'Call with no arguments first', stop and hand the user the `mustFirst` link if a prerequisite exists, and only buy after telling the user the exact price. It also scopes `another: true` to 'only when your user asked for a second IP' — clear when-to-use and when-not.

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 only the safety profile (readOnly/non-destructive/closed-world), and the description adds substantial behavior beyond that: the exact entry shape, the `{ connection: id }` naming convention, and critically the semantics of unusable logins — that needs_reauth/expired/logged_out sessions are not lost, that a run pauses with a link, and that re-auth restores the same id. This is context an agent cannot derive from annotations or the empty 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?

Front-loaded with what is listed, then the usage directive in bold, then the recovery semantics. It is longer than typical, but nearly every sentence carries actionable instruction (id naming, re-auth behavior, sibling routing) 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?

With no output schema, the description compensates by enumerating the returned fields and explaining how each is meant to be used, and it covers the full lifecycle an agent will hit (usable vs. needs_reauth/expired/logged_out). Nothing needed to call it or interpret its result 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. The description's field enumeration ('id', site, account, usable, timestamps) describes return values rather than inputs, which is still useful but not strictly parameter semantics.

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 ('List the saved logins this account already holds, one entry per login') and enumerates the returned fields, so an agent knows exactly what it gets. It is clearly distinguished from the sibling writers (add_connection, delete_connection) by naming their roles 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?

Gives direct when-to-use guidance ('Call this before any task that needs a login, and again whenever you come back to one later') plus an exclusion ('do not ask the user to sign in, just run the script') and a preference rule ('Prefer the login you used before over a new one'). It also routes to the two alternatives, add_connection and delete_connection, with the condition that selects each.

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 destructiveHint=false. The description adds the critical behavioral trait that no value is ever returned and no endpoint returns one, which is essential for an agent to avoid expecting secrets. It also specifies exactly what fields are returned. This adds significant transparency beyond 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 two short paragraphs. The first sentence states the purpose and returns, the second adds usage guidance. Every sentence is informative with no redundancy. It is front-loaded with the core action and 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 simple list tool with no parameters, the description is complete. It describes the output fields, the constraint on never returning values, and usage guidance with an example. No output schema exists, so the description carries the burden, which it does effectively.

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 schema already covers all parameters (none). The description adds no parameter details because none exist. Baseline 4 is appropriate for a parameterless 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 clearly states 'List the stored secrets this account holds, by NAME' and enumerates the returned fields, explicitly noting it never returns a value. It also differentiates from sibling request_secret by ordering. This is a specific verb+resource that distinguishes the tool.

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

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

The description explicitly instructs 'Call this BEFORE request_secret' and explains the rationale (avoiding sending user to a page for nothing). It also gives script usage example. This clearly guides when to use this tool versus the key alternative.

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: it explains what actually gets dropped (cookies), that the site session may be terminated when supported, and that the saved login itself is KEPT with status `logged_out`. It also interprets response fields (`siteLogout`, `siteSignedOut`) despite there being no output schema, clarifying exactly what is destroyed versus preserved.

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 side effects, then the routing rule. Dense and largely waste-free, though a few clauses (e.g., the parenthetical about `siteLogout: "supported"`) could be tightened without losing meaning.

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, the description covers the trigger, the side effects, the alternative tool, the retained state, and the meaning of return values. 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 description coverage is 100% and the single `id` parameter is already documented as coming from `list_connections`. The description restates that provenance but adds no format or syntax detail beyond the schema, 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 ('Sign a saved login out') and explicitly scopes it by the id returned from `list_connections`. It also pre-emptively differentiates itself from `delete_connection` by naming that sibling and contrasting their effects.

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

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

Gives an explicit trigger ('Call this when the user asks to sign out of a site') and names the alternative action plus its consequence ('delete_connection ... leaves the site session alive'), so the routing decision is fully specified.

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 (which only give generic readOnly/destructive/idempotent/openWorld flags) by stating the tool changes nothing on any website or account, costs the user nothing, records feedback only and never retries, and may return a 'supportRoom' live-chat channel with follow-up instructions. It also tells the agent to act without asking the user first, which is material for autonomous invocation.

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 purpose and the call-it-yourself instruction, then trigger conditions, then parameter guidance and escalation. Every sentence carries operational content, though the run is long for a two-parameter tool and the safety reassurance ('changes nothing, costs nothing') is stated more expansively than strictly needed.

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 values need no explanation, yet the description still flags the notable 'supportRoom' field and how to act on it. Combined with trigger conditions, parameter routing, and the no-retry contract, nothing an agent needs to invoke this 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 both parameters are already documented and baseline would be 3. The description adds real semantics on top: pass 'runId' when reporting a run, omit it when the report concerns a 'get_library' miss, and shape the 'report' body as one problem per submission covering what was asked, what came back, and which site.

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 ('Record what was missing, wrong, or incomplete') and immediately frames it against the siblings it depends on ('run' errors, 'get_library' gaps). An agent can tell this apart from 'run' or 'get_library' without opening either 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?

Enumerates explicit trigger conditions (run errors, timeouts, 'partial', empty results from a site that should answer, untrusted data, get_library misses) and an explicit escalation rule ('when the same task keeps failing... stop retrying and report it now'). It also states what this tool is not (it does not retry a run) and why it beats the alternative (support can read the run and fix the site's code, which another retry cannot).

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?

Discloses crucial behaviors beyond annotations: browser-side encryption, transcript/log exposure, refusal of non-human-readable names, and host-slot enforcement. None of these are visible in 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?

Front-loads the core mechanism, then uses bold directives for the two most safety-critical instructions. Despite length, every sentence earns its place by adding security, naming, or usage guidance.

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

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

Provides outcome (a link), user journey, lifetime range, preconditions, validation rules, and failure behavior. No output schema exists, but the return value is described sufficiently for 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 already covers all three parameters, so the baseline is 3. The description adds meaning for name (user-facing heading, months-later list row, naming refusals) and hosts (worth passing, refused elsewhere), though type semantics remain only 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 action: create a named empty secret slot and return a user-facing fill-in link. This clearly distinguishes it from lookup/listing siblings like list_secrets and get_secret_link.

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 preconditions: call list_secrets first and reuse an existing set secret, and instructs the agent to hand the link to the user rather than collect the secret. It does not explicitly compare with get_secret_link, so it loses a point.

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 openWorld/destructive/non-idempotent, and the description adds substantial context the annotations cannot: the ~55s client timeout versus 30-55s per capability call, the ~25,000 character result budget, `partial` meaning real-but-narrower results with `incomplete.failures[].fixable`, `needs_user` as a non-failure handoff, and `error` carrying no result. It also warns never to resend the script while `running`.

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 long, but tightly organized with bold headers, a bulleted status list, and the core action front-loaded; the final line defers files/secrets/billing to `get_library` rather than bloating further. The only cost is sheer density, which is warranted for a script-execution tool but still heavier than ideal.

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?

Despite arbitrary-code execution and an output schema, the description covers everything an agent needs to invoke and react correctly: script format, runId reuse, timeout math, result-size limits, the full status taxonomy, and the sign-in handoff path. Return-value explanation is rightly omitted because an output schema exists.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes well beyond the schema by defining the `script` parameter's contract: a plain async body rather than a wrapping function, the available globals (`URL`/`URLSearchParams`), the absent ones (`fetch`, `import`, `setTimeout`, filesystem), and the `return`/`log` conventions. That is genuine semantic value the schema alone does not convey.

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 action (execute a JS script body against the `bowmark` global on live websites) and the resource (real, open-world sites), and it explicitly positions itself relative to siblings by telling the agent to call `get_library` first and to use `wait_for_sign_in` for the handoff flow. An agent can tell what this tool is and where it sits in the workflow 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?

It states when to use the tool (`get_library` FIRST for function names, then `run({ script })`), when to reuse a runId versus resending a script, and how to branch on each `status` value (`running`/`partial`/`needs_user`/`error`). It also gives concrete sequencing guidance (one capability per script, `Promise.allSettled` instead of sequential awaits) and routes extended topics to `get_library({ query: "run guide" })`.

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, openWorldHint=false, and destructiveHint=false. The description adds integration context (internal inline run view) and a clear directive that agents should not invoke it, which is valuable beyond the structured 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?

Two short sentences, front-loaded with the integration purpose and then the routing instruction. 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 an internal UI-support tool, the description adequately explains what it is and why an agent should not call it, and it notes `run` returns the result. It leaves parameter behavior unexplained, but the no-call guidance reduces the practical 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 coverage is 0% and the description does not mention either parameter (`runId` or `script`). It provides no meaning, format, or usage for the parameters beyond the schema's bare types.

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 resource (a run's progress) and the context (inline run view), and explicitly distinguishes itself from the `run` sibling by saying `run` returns the result. However, the verb 'draw' is unusual and the tool's actual return or behavior is not operationally clear.

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 tells the agent not to call this tool and names the alternative (`run`) that provides the result. This is a clear when-not-to-use rule with an alternative.

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 establish this is a safe read (readOnlyHint=true, destructiveHint=false), and the description goes well beyond that: it discloses the blocking duration and cap, the full state machine returned (done/pending/cancelled/expired/unknown), the 15-minute link lifetime via expiresAt, and the prescribed agent action for each state. This is exactly the behavioral context annotations alone cannot 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?

The core action and the 'call it right after' instruction are front-loaded, and the per-state bullets are scannable. It is slightly verbose, repeating 'Send the SAME script again' across two states, but nearly every sentence carries actionable guidance.

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

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

With no output schema, the description fully carries the return-value burden by enumerating each state and the required follow-up. Combined with the timing and expiry details, an agent has everything needed to call this correctly and react to any outcome.

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 both parameters are already documented in the schema, and the description largely restates the same ref source and the same waitMs default/maximum. It does not add syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource (wait until the user finishes a sign-in link) and frames the scope precisely: it watches a live sign-in rather than driving it. It is clearly distinguished from siblings like add_connection (which issues the link) and run/run_view.

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?

Explicit when-to-use: 'Call it right after you give the user the link, in the same turn', with the prerequisite that the link be written first. It also states when it cannot be used (a ref starting 'site:' cannot be watched; wait for the user instead) and tells the agent not to ask the user whether they are done.

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