runnerID by Torchrunner

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

With no annotations, the description carries full burden. It reveals that this is a mutation (cancel) with a precondition, but does not describe side effects, reversibility, required permissions, error behavior (e.g., if already finished), or what the response contains.

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 of nine words with zero waste, and the key operation and precondition are front-loaded.

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 mutation tool with no annotations and no output schema, the description is too sparse. It omits critical invocation details such as what happens on success/failure, whether the operation is idempotent, and how to handle already-finished runs.

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 single required parameter run_id has 0% schema description coverage, yet the description provides no additional meaning about what run_id refers to (e.g., a run identifier from handoff_task or get_run) or its expected format. The schema's UUID format is the only clue.

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 ('cancel') and resource ('handoff') plus a precondition ('has not finished'). It implicitly distinguishes from siblings like get_run (read) and handoff_task (initiate), though it does not name alternatives 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?

Usage is implied by the precondition 'has not finished', suggesting it applies only to active handoffs. However, there is no explicit guidance on when to use this versus get_run to check status, or what to do if the handoff is already finished.

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?

No annotations are provided, so the description carries the full behavioral burden. It does useful work by disclosing that the code is not returned (so the agent must not expect the value back) and that the action happens over CDP on a 'matching page'. It omits major traits for a mutation-style browser action: whether typing submits the form, what happens when no page matches the site, whether existing field content is replaced, and what errors surface.

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 with no filler, and the primary action is front-loaded. 'The code is not returned' is a compact, high-value caveat that 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 4-parameter browser-automation tool with no annotations and no output schema, the definition is minimally adequate. It never explains how the target page is chosen from 'site', what 'selector' overrides, or what failure looks like when no matching page exists – gaps an agent would hit on first call.

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 only 25% – only identity_id is documented in the schema, while site, cdp_url, and selector are bare strings. The description adds no meaning for any of them; 'matching page' gestures at site-based page selection but never defines the matching rule, and 'selector' is never explained at all. With low coverage the description should compensate, and it does not.

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: type the authenticator code into the matching page over CDP. The word 'authenticator' distinguishes it from the sibling fill_email_code, and 'type ... into the page' distinguishes it from get_authenticator_code, which retrieves the code. It stops short of naming an alternative explicitly, so a 4 rather than a 5.

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

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

The description implies the usage scenario (you have obtained an authenticator code and now need to enter it into a page), and 'The code is not returned' hints that get_authenticator_code must be used first to obtain it. However, no condition is stated for choosing this over fill_email_code or fill_login, and no when-not case or prerequisite is spelled out.

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?

With no annotations, the description carries the full burden; it does disclose the two most surprising traits — it mutates the page by typing, and it withholds the code from the caller. It says nothing about timeout behavior (though a timeout_seconds param exists), what happens if no email arrives, or how 'matching page' is resolved among multiple tabs.

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

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

Two tight sentences, front-loaded with the action and ending on the critical caveat about the return value. Nothing is padded, though the brevity comes at the cost of the missing detail noted elsewhere.

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?

Five parameters at 20% coverage, no annotations, and no output schema: the description would need to explain the CDP target, page-matching inputs, and timeout semantics to be callable with confidence, and it explains none of them. An agent knows roughly what happens but not how to parameterize or interpret failure.

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 only 20% — four of five parameters (site, cdp_url, selector, timeout_seconds) have no schema description, and the description compensates for none of them. 'Matching page' vaguely gestures at site/selector but gives no meaning, and cdp_url — the sole required parameter — is never explained.

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 chain (wait for a code, type it into a page over CDP) and the resource (email code), which clearly separates it from read-only siblings like get_email_code. It stops short of naming which sibling to use instead, so differentiation is inferential rather than explicit.

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 clause 'The code is not returned' implicitly routes agents that need the code value to get_email_code or wait_for_email_code, and the CDP/page framing hints at the browser-driving context. But no sentence states when to prefer this over fill_code or wait_for_email_code, and no prerequisites (open CDP session, an email already triggered) are given.

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?

With no annotations, the description carries the full burden, and it does disclose one important trait: the password is not returned. However, it omits whether the form is submitted (the schema has a `fields.submit` entry), what happens on failure, what permissions/state are required, and whether navigation occurs.

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

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

Two tight sentences with zero waste, and the security-relevant note ("password is not returned") is placed where it will be read. Nothing redundant 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?

For a 4-parameter tool with a nested object, no output schema, no annotations, and 25% schema coverage, this is far too thin — the meaning of `fields` and `cdp_url` and the submit behavior are all left unexplained.

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 only 25% (only `identity_id` documented), and the description says nothing about `site`, `cdp_url`, or the nested `fields` object with username/password/submit — the reader cannot tell whether those are CSS selectors, field names, or literal values. It does not compensate for the coverage gap.

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 ("Type the saved username and password into the matching page over CDP") and clearly occupies the credential-filling slot among siblings like fill_code, get_email_code and open_magic_link. The phrase "matching page" is left undefined (matching which site? the `site` param presumably), which keeps it from a 5.

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?

There is no explicit when-to-use or when-not-to-use guidance, no mention of the prerequisite that a login must have been saved via save_login, and no routing versus fill_code/fill_email_code/restore_session. The agent must infer usage entirely from the verb.

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?

With no annotations, the description carries the full burden and does well: it discloses the ~30-second lifetime, that the release is audit-logged, and that the underlying seed is never exposed. It stops short of stating permission/identity requirements or what happens when the code has expired or the site is unknown, so it is strong but not exhaustive for a credential-adjacent tool.

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

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

Three short sentences, zero filler. Purpose and constraint come first, then the TTL/audit/no-seed disclosure, then the sibling routing hint — a well front-loaded ordering.

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 2-parameter tool with no annotations and no output schema, the description supplies the return shape (six digits), its validity window, and the security guarantee that the seed is not returned. The only real gap is the meaning/format of the required site parameter, which neither the schema nor the description explains.

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 only 50%: identity_id is documented in the schema (omit when the account has exactly one identity), but site has no description anywhere. The description mentions "site" only in passing and never says whether it is a domain, a saved-site label, or how matching works, so the undocumented parameter is not compensated for.

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 ("Return the current six-digit authenticator code") and names the constrained scope ("for a site") plus the audience condition ("agents whose browser runnerID cannot reach"). It explicitly separates itself from the sibling fill_code, so an agent can distinguish it 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 both the when-to-use condition (browser runnerID cannot reach) and the preferred alternative with its triggering condition ("Prefer fill_code when you have a cdp_url"). That is an explicit routing rule between two competing tools, which is exactly what usage guidance should do.

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?

With no annotations, the description carries the burden and does well: it discloses the blocking wait, the destructive side effect ('the code is consumed'), and an audit trail ('the release is logged'). It does not say what happens on expiry/timeout, which matters for a 1-120 second wait.

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

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

Three short sentences, front-loaded with the action, then the side effect, then the alternative. Every clause carries information; nothing is redundant.

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?

No output schema exists, and the description does state the return value (the code) and its post-conditions, so the core is covered. Gaps remain around timeout behavior, the meaning of `site`, and disambiguation from wait_for_email_code — non-trivial for a side-effecting wait tool with zero annotation coverage.

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 only 33% — only identity_id is documented in the schema — yet the description explains neither `site` (which site/domain is polled?) nor how `timeout_seconds` affects the wait or what occurs if it elapses. With low coverage the description is expected to compensate and it does not.

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 concrete verb and resource ('Wait for an emailed verification code and return it') plus the agent condition it serves (browser runnerID can't reach). It does not, however, distinguish itself from the very similarly named sibling wait_for_email_code, leaving that confusion unresolved.

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?

'Prefer fill_email_code when you have a cdp_url' and 'for agents whose browser runnerID cannot reach' give an explicit selection rule against one alternative. It omits any guidance versus wait_for_email_code, the closest-sounding sibling, so the routing is clear but incomplete.

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?

With no annotations, the description carries the full behavioral burden; it does disclose that this is a read and that the result contains no secrets, which is genuinely useful safety context. It omits error behavior for a missing identity, what happens when multiple identities exist, and what fields beyond the inbox address 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 short sentences, front-loaded with the action and followed by the most decision-relevant property (no secrets). Nothing is redundant.

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 read with no output schema and no annotations, the description is nearly complete: it names the payload highlight (inbox address) and its confidentiality. Only the returned field set and error semantics are missing, which are minor at this complexity.

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 single identity_id parameter is fully documented in the schema, including the omission rule for single-identity accounts. The description adds nothing about the parameter, so the schema does all the work and 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?

"Read one identity" gives a specific verb plus resource, and "including its inbox address" adds scope detail. It does not explicitly differentiate itself from siblings like get_email_code or list_events, so an agent must infer the boundary from the noun alone.

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

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

There is no explicit when-to-use statement, no mention of alternatives, and no prerequisites. Usage is only implied by the resource name and the mention of the inbox address, which suggests the tool is for resolving an identity to its address.

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?

With no annotations, the description carries the full burden and does well: it declares this a read operation and explains the non-obvious blocking behavior of wait_seconds (waits up to 120s for a change before returning). It also discloses what the response contains, compensating for the absent output schema. It stops short of stating permission requirements or whether the wait can time out returning an unchanged status.

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 dense sentences with no filler. The return payload is front-loaded and the blocking parameter gets its own explicit clause, so nothing needs to be re-read.

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

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

For a two-parameter, no-annotation, no-output-schema read tool, the description covers the essential behavior including the blocking wait and the shape of the result. The remaining gap is the unstated meaning of run_id and any timeout/permission behavior, which is minor but real.

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

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

Schema description coverage is 0%, so the description must compensate. It gives solid semantics for wait_seconds, including the 120-second cap and the 'wait for change' behavior, but run_id is never explained beyond the implicit 'the handoff to read' — it is left to the schema's uuid format to 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 states a clear verb (read) and resource (a handoff/run) and enumerates what is returned: status, result on completion, failure reason, or a waiting reason. The only friction is terminology: the tool is named get_run but the description consistently calls the object a 'handoff', which the agent must infer maps to the run_id.

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: poll this to check status, or pass wait_seconds to block for a change. There is no explicit guidance on when to prefer it over siblings like wait_for_approval, list_events, or handoff_task, and no exclusions or prerequisites are given.

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?

With no annotations provided, the description carries the full burden and does well: it discloses that runnerID acts as this identity in its own browser, pauses for owner approval before anything risky, and returns immediately with a run_id (async). It doesn't cover failure modes, rate limits, or permissions, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the action and when to use it, then the behavioral contract, then the follow-up call. Every clause earns its place.

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

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

For a 6-parameter async delegation tool with no output schema, the description covers the lifecycle (returns run_id, read via get_run) and the approval/identity behavior. It could say more about what happens on failure or approval denial, but an agent has enough to invoke and follow up 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%, so the schema already documents every parameter. The description hints at identity usage ('as this identity') and result shape ('returns the result', 'call get_run'), but adds no syntax or format guidance beyond the schema, matching the baseline 3.

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 ('hand ... a step you cannot finish') and even gives a concrete example ('work on a site you cannot sign in to'). It distinguishes itself from get_run by explicitly naming that sibling as the way to read results, giving an agent a clear mental model.

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?

Clearly signals when to reach for it (steps the agent cannot complete itself, e.g. authenticated sites) and routes result-reading to get_run. It stops short of explicit exclusions or listing other alternatives, but the context is unambiguous.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that results are newest-first and that event data excludes secrets, but it does not explicitly confirm read-only behavior, pagination, event retention, or permission requirements.

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 with no wasted words, and the core purpose is front-loaded before the security note.

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 listing tool this is minimally adequate, but with no annotations and no output schema it leaves out important call behavior such as how limit affects results and what the returned event objects contain. It covers the basic action and one safety property but not enough to be complete.

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 50%: identity_id is well documented in the schema, but limit has no schema description and the tool description does not explain its default, maximum, or pagination implications. The description does not compensate for the undocumented limit parameter.

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

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

The description gives a specific verb and resource ("List recent events"), scopes it to an identity, and specifies ordering ("newest first"). No sibling tool appears to list events, so the agent can distinguish this from the authentication-action 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?

It implies the context of retrieving events for an identity but gives no explicit when-to-use guidance, exclusions, or alternatives. The agent must infer why it would choose list_events over get_identity or other identity-related siblings.

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

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

With no annotations, the description must carry the full behavioral burden, and it does disclose genuinely useful traits: the call blocks/waits rather than returning immediately, and it validates the link host against `site` plus trusted subdomains. It omits what happens on timeout or mismatch, whether a default timeout applies, and what the caller observes on failure, so it is not fully transparent for a blocking operation.

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

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

Three short sentences, front-loaded with the action, with no filler. 'site is required' partly duplicates the schema's required list, a small redundancy but a defensible emphasis given the low schema coverage.

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

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

For a 4-parameter, annotation-free, output-schema-free blocking tool, the description covers purpose and domain-matching behaviour but leaves out timeout semantics, error/timeout outcomes, and the meaning of `cdp_url`. An agent could call it, but would be guessing about failure handling and the browser connection parameter.

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 only 25% — just `identity_id` is documented. The description adds real meaning for `site` (it is the expected link host, not a URL to visit), but it never explains `cdp_url` (apparently a browser connection endpoint) or the bounds/behaviour of `timeout_seconds`, leaving two of four parameters opaque in both schema and 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 compound action: wait for a magic link and open it, scoped to links whose host is `site` or a trusted subdomain. This is distinguishable from siblings like wait_for_email_code or fill_code, which return or submit codes rather than opening a link. It does not explicitly name a sibling it differs from, which keeps it at 4.

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?

There is no explicit when-to-use guidance, no mention of prerequisites (e.g. that a magic-link email must already have been triggered), and no routing to alternatives such as wait_for_email_code or fill_email_code. The only conditional information is a restatement that `site` is required.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that approval_id and status are returned and that the email token is not returned, but it omits whether the call triggers an email, whether repeated calls create duplicate requests, and what happens on denial or timeout.

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 with zero waste, and the core action is front-loaded before return behavior and the email-token caveat.

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 no annotations, a nested details object, and no output schema, the definition is too thin. It does not explain the details parameter, the approval lifecycle, or how it relates to wait_for_approval, leaving the agent with material gaps.

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 33% and only identity_id is documented in the schema. The description does not explain the action parameter's meaning or the shape/content expected in the nested details object, so it fails to compensate for the low 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?

States a specific verb and resource: asking the account owner to approve an action. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling wait_for_approval.

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 no guidance on when to use this tool versus wait_for_approval, or any prerequisites such as an owner needing to be configured. Usage is only implied by the phrase 'Ask the account owner to approve.'

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?

With no annotations, the description carries the full burden. It does disclose one useful behavior ('Cookie values are not returned'), but omits whether existing browser state is overwritten, whether it requires a live CDP connection, what happens if the session is stale, and what the response actually contains.

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 action and destination, zero 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?

No output schema, no annotations, and low parameter coverage mean the description should do more. Critical gaps remain: the return payload shape, the precondition that a session must already be saved, and failure behavior for an unreachable cdp_url.

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 only 33% — identity_id is documented, but 'site' and 'cdp_url' have no descriptions. The description only clarifies that cdp_url points at the target browser, and leaves 'site' (domain? URL? identifier?) entirely undefined.

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

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

Names a specific verb+resource ('Restore a saved session') and the destination ('into the browser at cdp_url'), which pairs clearly with the sibling save_session. It doesn't explicitly name save_session as the counterpart, but the semantics are 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?

No explicit when-to-use guidance or alternatives are given. The phrase 'a saved session' weakly implies a prior save_session call, but nothing states prerequisites, when not to use it, or how it relates to save_login/fill_login flows.

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?

With no annotations at all, the description carries the full behavioral burden, and it does disclose two genuinely useful traits: the seed is encrypted and it is not returned. It omits other important behavior — whether an existing seed for the same site is overwritten, what permissions or session state are required, and what errors occur on duplicate or invalid seeds.

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, zero filler, with the encryption/non-return guarantee placed immediately after the core action. Nothing in it is redundant.

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 secret-writing mutation tool with no annotations and no output schema, the definition covers the essentials (what is stored, that it's encrypted and not echoed back) but leaves gaps an agent would care about: overwrite semantics, auth requirements, and failure modes.

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 33% (only identity_id is described in the schema), so the description must compensate. It does add real meaning for seed (base32 or an otpauth:// URI), which the schema only types as a 1-2048 char string, but 'site' remains ambiguous — URL, hostname, or arbitrary label — and identity_id is only covered by 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?

A specific verb plus resource: 'Store an authenticator (TOTP) seed for a site,' with the two accepted seed formats (base32 or otpauth:// URI) spelled out. The write-side purpose is self-evidently distinct from the sibling read tools get_authenticator_code and fill_code, though no sibling is named explicitly.

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

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

Usage is only implied: an agent infers it should call this when it holds a TOTP seed to persist. There is no explicit when-to-use, no mention of prerequisites (e.g. an active session/identity), and no stated alternative for related flows.

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?

With no annotations, the description does most of the work by disclosing that the secret is encrypted and is not returned, which is meaningful behavioral context for a credential-storing tool. However, it does not say whether existing logins are overwritten, whether the operation is idempotent, what permissions or identity are required beyond the schema note, or what the response contains.

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 with no wasted words. The core action is front-loaded, and the secret-handling caveat follows immediately.

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?

This is a four-parameter mutation tool with no annotations, no output schema, and only partial parameter documentation. The description adds one useful behavioral fact about the secret but leaves too much unsaid about overwrite behavior, identity requirements, and the result of the call.

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 only 25%; identity_id is documented in the schema, but site, username, and secret have no semantic explanation in the description or schema. The description mentions 'secret' but only to explain its handling, not its format or parameter semantics, so it fails to compensate for the low 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 gives a clear verb and resource: 'Store a site login.' An agent can tell this saves credential records rather than sessions or authenticator entries, though the sibling tools save_session and save_authenticator are not explicitly contrasted.

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?

There is no guidance on when to use this tool versus save_session, save_authenticator, or fill_login. The only implied usage is that a login is being persisted, but no prerequisites, exclusions, or alternatives are 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?

No annotations exist, so the description carries the full burden. It does add one useful behavioral fact — 'Cookie values are not returned' — which tells the agent secrets are not exposed in the response. But for a write/persistence operation it omits whether an existing saved session is overwritten, where the data is stored, and what permissions or session state are required.

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 with zero filler; the core action and scope are front-loaded, and the return-behavior caveat follows immediately.

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?

No output schema and no annotations mean the description alone must cover behavior, and it only covers the response caveat. Missing pieces — overwrite semantics of an existing saved session, 'site' format, and required browser/session state — matter for calling 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 only 33% (only identity_id is documented), so the description must compensate; it partially does by framing cdp_url as a browser endpoint URL and site as a single site. However, it gives no format conventions for 'site' (domain vs. full URL) and nothing about cdp_url validity, leaving both required parameters underspecified.

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 cookies and localStorage') with a clear scope limit ('for one site') and the source ('browser at cdp_url'). It does not explicitly name restore_session as its counterpart, so sibling differentiation is only implied.

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

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

Usage is implied by the pairing with restore_session in the sibling list, but the description never says when to call this versus restore_session, nor states any prerequisite such as the browser needing to be an authenticated live session. No exclusions are given.

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?

No annotations are provided, so the description carries the full burden. It does disclose the key blocking behavior and both exit conditions, plus the 30-second default, which is genuinely useful. However, it omits what happens on timeout (error vs. a 'still pending' result) and whether the call holds a session or has side effects, which are the details an agent most needs before blocking on it.

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, zero filler, and the behavioral contract is front-loaded before the parameter detail. Every clause 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?

For a simple three-parameter blocking tool this is close to adequate, but with no output schema and no annotations the description should state what the call yields on success versus timeout. That missing outcome contract is the main gap for an agent deciding how to branch afterward.

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 only 33%, and the description compensates for exactly one gap by stating that timeout_seconds defaults to 30 — a value absent from the schema. It says nothing about approval_id (the required parameter) or its relationship to request_approval, so the low-coverage burden is only partially met.

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 and resource ('wait until an approval is no longer pending') and states both termination conditions, so the operation is unambiguous. It does not explicitly differentiate itself from the sibling request_approval, though the pairing is inferable from the names.

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 only implied: the agent can infer this should be called after request_approval to block until a decision arrives. There is no explicit 'use this when...' statement, no guidance on when not to call it (e.g., polling vs. blocking), and no mention of the sibling alternatives such as list_events for non-blocking checks.

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?

With no annotations, the description carries the burden and mostly does: it discloses the destructive-ish side effect (code is consumed) and the handoff tool. It omits blocking semantics and what happens on timeout (error vs. silent return), which matter for a wait tool.

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, no filler, with the consumption warning and the follow-up action front-loaded. 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?

No output schema and no annotations, so the description is the only carrier of behavior; it covers the consumption and the handoff but leaves blocking duration, timeout failure mode, and the site parameter unexplained. Adequate to avoid misuse, but a blocking tool deserves more.

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 only 33%; only identity_id is documented in the schema and the description adds no meaning for site or timeout_seconds. The description does not compensate for the low coverage, so the agent must guess whether site scopes the mailbox and how the timeout bounds the wait.

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

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

Specific verb+resource ('Wait until an email code arrives') with the key disambiguator that the code is consumed and not returned, which separates it from retrieval-style siblings like get_email_code. It stops short of explicitly naming the sibling it competes with, so the 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?

Explicitly routes the agent to the follow-up tool: 'Use fill_email_code to type it into the page.' The consumed-and-not-returned note tells the agent this is not a read path, but it never says when to prefer get_email_code instead or what to do if waiting is inappropriate.

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