Bowmark web data: LinkedIn, Amazon, YouTube, Reddit, Airbnb, Instagram

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

Goes well beyond the annotations: no site is touched, a match-nothing query returns an explanation rather than an error, a broad query can return a sliced list where absence proves nothing, and login-gated sites only work with an existing provider/connection. It also discloses the follow-up pattern (call again with an index entry's name for types and examples). All consistent with readOnlyHint/openWorldHint=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-loaded with the primary trigger and bold section headers, but it is long and repetitive for a three-parameter lookup — the 'Checking is cheap, so check' paragraph and the closing loop restate guidance already given. Several clauses could be cut without losing instruction.

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

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

With no output schema, the description carries the burden of explaining returns, and it does: capability functions, per-site provider functions, an index when no query is given, and one-line output under `minimal`. Truncation behavior is flagged. Only the exact shape of a sliced response is left vague.

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 adds real semantics beyond the schema: a hostname is what settles single-site coverage (a name matching nothing proves nothing), and a returned index entry should be re-queried by name for its types and examples. Multi-part tasks should use `queries` in one call rather than repeating calls.

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 makes clear this is a capability/index lookup ('It answers whether Bowmark can already DO the thing') and later states plainly 'What comes back is the function library you write against.' It distinguishes itself from the execution sibling by describing the loop 'get_library → write a JS script → send it to run.' The framing is somewhat indirect (it never says 'returns a list of callable functions' up front), which keeps it below 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?

Explicit when-to-use ('whenever a task touches a live website', 'for Bowmark questions too'), when-not ('Behind a LOGIN it works only where a provider exists'), and cost of a wrong call ('If nothing fits, you lost one cheap call; use your normal approach'). It also routes between its own parameters (query vs queries vs minimal) and names the follow-on tool (run).

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the values are authoritative invoice-matching charges, itemized by SKU line item, and the past-month-only scope. It doesn't discuss latency, API-key requirements, or data freshness, which keeps 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?

Front-loaded with the core purpose, then argument behavior, then return shape. Every sentence is relevant, though the sentence enumerating `totalUsd`, `sku`, `quantity`, `unit`, and `usd` partially duplicates the existing output schema and 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?

For a single-optional-parameter read tool with full annotation coverage and an output schema, the description supplies everything an agent needs: default behavior, accepted format, and the authoritative nature of the numbers. Repeating return fields is minor redundancy rather than a 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 100% and the single `month` parameter already documents the YYYY-MM pattern and the omit-for-current default. The description restates the same format and adds one concrete example (`2026-09`), plus the implicit constraint that only past months are queryable, but that is marginal value over the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'See the real cost of calls on this account', itemized by provider calls, browser sessions, and IP leases. It explicitly contrasts with an implied alternative (estimated costs) by asserting this is the EXACT amount matching the invoice, so an agent can recognize this is the billing/cost tool and not a usage-metrics or reporting sibling.

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 concrete invocation guidance: omit arguments for the current month, pass `month: 'YYYY-MM'` for a past month. It does not name a sibling alternative or exclusion, but no sibling in the list offers cost data, so the routing decision is essentially 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?

Annotations already declare write (readOnlyHint=false), idempotent and non-destructive; the description is consistent with them and adds the non-obvious context that this is an internal side-effect invoked by an open jig and that only the "last good" result is retained. It does not say what happens on repeated writes or whether a prior cached value is replaced, but the essential behavioral framing is present.

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 redundancy, and the most decision-relevant fact ("You do not need to call this") is present up front rather than buried. Nothing could be removed without losing 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 three-parameter internal write tool with full schema coverage and an output schema, the description supplies what an agent actually needs: that it is auto-invoked and that agent-side calls are unnecessary. Minor gaps (overwrite semantics, error behavior) are tolerable given the annotations and schema.

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

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

Schema description coverage is 100%, so the schema already explains key, jigId and value in detail. The description adds only marginal meaning (the value is a "last good result" saved for reopening the page), which is essentially a restatement of the schema's own parameter description. Baseline 3 applies when the schema does the heavy lifting.

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

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

"Used by an open jig to save a call's last good result" names a concrete verb (save) and resource (a call's result) and ties it to the jig lifecycle, which separates it from siblings like jig_call or jig_get. It stops short of naming any single sibling it overlaps with, but the internal/auto-invoked framing makes its role distinguishable.

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?

"You do not need to call this" is an explicit when-not-to-use instruction, which is stronger than most definitions provide. It lacks a positive case (any condition under which an agent might legitimately call it), so it is not fully complete guidance.

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

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

Annotations declare destructiveHint=true, non-idempotent, and openWorld, so the agent already knows this has external side effects and is unsafe to repeat. The description adds nothing about what those side effects touch, how parallel calls in `calls` interact, or what the returned `runId` means for later collection. With a destructive, open-world tool, that is a meaningful gap rather than a covered one.

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 wording, and the redirection to `run` is given immediately. The only structural weakness is that the primary purpose sentence is largely negated by the second, so the takeaway is front-loaded but slightly self-defeating.

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

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

The tool has six parameters, a destructive/open-world profile, and an output schema, yet the description supplies only a one-line identity and a do-not-use note. It never covers the cancellation semantics via `ref`/`cancel`, the timeout-to-`runId` handoff, or the parallel execution model, all of which are non-obvious behaviors an agent would otherwise have to infer from the schema alone.

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

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

Schema description coverage is 100%, and the schema already explains `ref`, `calls`, `jigId`, `runId`, `cancel`, and `timeoutMs` in detail. The description contributes no additional parameter meaning, so the baseline of 3 is appropriate when the schema carries the full burden.

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

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

The description states a specific verb and object ("call the library") and scopes it to "an open jig," which distinguishes it from generic tools. However, the immediate follow-up ("You do not need to call this") undercuts the stated purpose and never clarifies what the library is or what a library call produces, leaving the intent only loosely defined.

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

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

It explicitly names the alternative ("use `run`") and rules out direct agent invocation, which is exactly the routing information an agent needs to avoid misfiring. It stops short of a full 5 because it doesn't describe the positive condition under which this tool is invoked (i.e., what an open jig actually does with it).

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

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

Beyond the annotations it discloses the security model that matters most: the copy runs as the requesting user with their own logins, never the author's, and can call only the functions its listing lists. It also explains the non-obvious idempotent-like behavior (existing copy returned with `alreadyHave: true`), which materially refines the `idempotentHint: false` signal, and names the auth step (`sitesNeedingLogin`, one-time sign-in links) the caller must complete.

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?

Roughly five sentences, each carrying distinct load: purpose, sandbox/auth model, identifier formats, duplicate handling, and the post-call workflow. It is front-loaded with the verb and scope, and no sentence restates the tool title or schema verbatim without adding 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 two-parameter mutation with announcements in the annotations, the description supplies everything an agent needs: identity/permission semantics, duplicate behavior, the login handshake, and the terminal `jig_open` step. Return fields are covered by the output schema and are only summarized here, which is appropriate.

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; the description goes further by tying `another` to the decision condition (only when the user wants a second copy) and reiterating the accepted `listing` formats from `jig_search`. It does not add new format or validation detail beyond the schema's own enumeration of the three accepted forms.

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?

"Copy someone's published jig into THIS user's account, from its current version" gives a specific verb (copy), a specific resource (published jig), and an explicit scope (this user's account, current version). It is immediately distinguishable from siblings like jig_search (find a listing), jig_open (open a copy), and jig_publish (publish your own).

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 where the `listing` value comes from (`jig_search`), when the existing copy is returned versus when to pass `another: true` (only when a second copy is wanted), and the exact follow-up sequence: surface each `signInUrl`, call `wait_for_sign_in` with its `ref`, then `jig_open({ jigId })`. When-to-use, when-not-to-use, and alternatives are all covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: result ordering, and the conditional shape of `forkedFrom` ({ listingId, versionNo }) and `updateAvailable` (version number or null) that only appear on forked copies. It stops short of noting pagination or result-size limits, which matters for a full listing.

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 returned, then the conditional fork fields, then the usage trigger, then the follow-up action — a sensible ordering with no filler sentences. The per-field enumeration overlaps somewhat with the existing output schema, so a small amount of the text is restating structured data.

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

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

With zero parameters, rich annotations, and an output schema carrying return values, the description covers everything an agent still needs: what the list is, how it is ordered, which fields are conditional, and what to do next. No material gap remains for a read-only listing 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter meaning to add. The only parameter referenced (`jigId`) belongs to the follow-up `jig_open` call, which is framed usefully but is not this tool's input.

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?

Uses a specific verb and resource ('The jigs this user has') and enumerates exactly what each entry contains (id, slug, title, source built-in, last-changed time), plus ordering ('newest change first'). That is enough for an agent to distinguish this enumeration tool from jig_get, jig_search, or get_library without opening a schema.

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

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

Gives a concrete trigger ('when the user mentions a page they made before', with example phrases) and a clear follow-up chain: reopen with `jig_open({ jigId })` rather than rebuilding, and offer `jig_pull_update` when `updateAvailable` is set. It does not state when to prefer a sibling lookup tool (jig_get/jig_search) instead of listing everything, so the exclusion side is 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered without the description. The description earns credit by disclosing what the call actually surfaces beyond a plain read — user actions (watched, hid, searched), load speed, failed calls, and an `advice` block naming what to fix — which explains why an agent should call it repeatedly rather than treat it as a one-shot fetch.

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

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

It is front-loaded with the payload ('See what an open jig is showing the user right now') before the procedural guidance, and every sentence does work. It is slightly dense — the final sentence packs perf, advice, and the remedy into one line — but there is no filler.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to explain purpose and sequencing, which it does. The one real gap is its failure to situate itself relative to the other read-oriented jig tools in a crowded sibling set.

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

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

There is a single required parameter (jigId) with 100% schema description coverage, including where to obtain the id from jig_open or jig_list. The description adds nothing about the parameter, which is the expected baseline when the schema already carries full 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?

The description names a concrete operation on a concrete resource: inspect what an open jig is currently displaying (items, view, recent user actions, state, perf, advice). That is far more specific than the title's 'Look at a page'. It does not, however, distinguish itself from the similar-sounding read siblings jig_get, jig_read, and jig_view, which an agent would plausibly confuse it with.

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 explicit and paired with an alternative: call it before curating, when the user says 'clear the slop' or 'why is this here', then change things with jig_update, and fix what `advice` names via jig_update. There is no when-not guidance, and the read-side siblings (jig_get/jig_read/jig_view) are never positioned against this tool, so the routing story is incomplete on the read side.

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

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

Beyond the annotations it discloses real behavioral traits: a link/tab is returned, library calls are metered for this user, sign-in-requiring calls pause behind a banner, and the page runs sandboxed with no fetch or external script/style/font. It does not say what permissions the open itself needs or how failures of creation surface, keeping it below a 5.

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

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

The core concept is front-loaded, but the body drifts into page-authoring instructions (bowmark.call/batch, skeletons, `bowmark.img`, load-speed advice) that it also says 'see the guide' for, making it long and repetitive for a tool whose job is to open a page.

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

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

Output schema exists, so return values need not be restated, and the description covers the full create/reopen/curate workflow and constraints. What is missing is narrower: auth/permission needs for the open call and any quota or error behavior specific to creation.

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 adds prioritization the schema lacks – `files` is the default for a real page, `html` is legacy/toy-only, `jigId` must be passed alone, and `state` is the handle for later `jig_update` steering.

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 verb+resource in plain terms ('Make the user a "jig": their own copy of a website') and immediately contrasts it with siblings – `jig_update` for live changes, `jig_open({jigId})` to reopen, `jig_look` to inspect. The concept needs the explanation it gives, but the core action is unambiguous.

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

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

Explicit decision rules: start from `template` when one fits, otherwise write `files` (React, one file per view), use `html` only for a toy, call `get_library({ query: "jig guide" })` FIRST, and reopen with `jigId` rather than rebuilding. Alternatives and exclusions are both named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false; the description's claim that it is called automatically by an open jig is consistent with the non-read-only, idempotent profile. It adds no detail on what is written, whether failures are retried, or how the report payload is shaped, so it adds only modest value beyond the annotations.

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

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

Two short sentences with zero filler, and the caller identity is front-loaded before the opt-out instruction. Nothing could be removed 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 two-parameter telemetry tool with a full schema and an output schema, the description covers what an agent needs: what it is and that it is not required. Only a note on when an agent would ever invoke it (debugging a slow open) 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 description adds nothing about jigId or the report object beyond what the schema already says. Baseline 3 applies since the schema carries the parameter burden entirely.

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 function — reporting load performance back to the jig runtime — and implicitly distinguishes itself from the user-facing jig_* tools by naming 'an open jig' as the caller. It is not a tautology of the name, though 'jig_perf' alone would not have conveyed the telemetry meaning.

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

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

Provides an explicit exclusion: 'You do not need to call this,' which is exactly the guidance an agent needs to skip the tool. It does not, however, name a condition under which an agent might legitimately need it (e.g. debugging) or point to a sibling for that purpose.

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

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

Goes well beyond the annotations (which only say non-read-only, open-world, non-idempotent): it discloses the versioning model (snapshot AS THEY ARE NOW into N+1), that later edits stay private, that `handle` and `slug` are permanent, and that screenshots must be captured by the agent with sample data. It does not discuss rate limits, failure modes, or what happens to an existing listing's version history on republish, which keeps it off a 5.

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

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

Front-loads the core action and the versioning consequence, then routes through dry-run, handle prerequisite, visibility, and detailsOnly in a logical order. It is dense and long for a single block — the em-dash parentheticals and 'AS THEY ARE NOW' emphasis add length — but nearly every clause carries decision-relevant 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 14-parameter mutation tool with nested screenshot objects, the description covers the prerequisites, the destructive/private-data concerns, the dry-run safety path, and the two publish modes; the return value (jig URL) is stated even though an output schema exists. Nothing an agent needs to call it correctly appears absent.

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

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

Schema coverage is 71%, and the description still adds real meaning beyond it: disambiguates `jigId` vs `jigSlug` in prose, explains `defaultState` as the place to blank personal data, and clarifies the agent's responsibility for `screenshots`. It adds little on `slug`, `title`, `tagline`, `changelog`, `description`, and `extraSites`, which are left largely to the schema.

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

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

States a specific verb and resource ('Publish the user's jig ... as a listing others can get') and immediately distinguishes it from related siblings by naming `jig_set_handle` and by explaining that `detailsOnly: true` avoids writing a version (contrast with `jig_update`). The snapshot-to-version-N+1 mechanic makes the operation unmistakable.

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 guidance across every branch: call `dryRun: true` first and show the user the payload, first publish requires a public `handle` (with the pre-req flow via `jig_set_handle`), `detailsOnly: true` for unlisting or metadata changes. It also spells out what each visibility value means, 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?

Reaffirms the read-only profile already carried by `readOnlyHint` with the plain statement 'Writes nothing', and adds genuinely new behavioral context: what the three returned pages mean, what `edited` implies for the merge path, and that `newFunctions`/`widenedFunctions` require user approval before the page can use them. It doesn't cover error cases (e.g., no update available, stale version), which keeps it from 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?

The precondition is front-loaded and the prose is dense with no filler, but several sentences describe the downstream merge-and-save workflow rather than this tool itself, which lengthens it beyond its minimal scope. Still efficient and readable.

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?

Although an output schema exists, the description voluntarily explains the semantics of the three page values and the two function-permission fields, which is the non-obvious part of interpreting the result. Combined with the workflow guidance, nothing an agent needs to call 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?

The single parameter `jigId` has 0% schema description coverage, and the description only mentions `jigId` in the context of the follow-up `jig_update` call, not as this tool's input. It is inferable that it identifies the user's copied jig, but that is never stated outright, so the description only partially compensates 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+resource: it pulls the three pages (`base`, `theirs`, `mine`) that a merge of a copied jig requires. It explicitly scopes the situation to a jig obtained from someone's listing and names `jig_list` and `jig_update` as the surrounding tools, so the agent can distinguish it from siblings without opening a schema.

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

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

Gives both the trigger condition (`jig_list` shows `updateAvailable`) and the branch logic: if `edited` is false, save `theirs` as is; otherwise merge `mine` and `theirs`. It also names the concrete follow-up call, `jig_update({ jigId, html, mergedFrom: theirsVersion })`, so the agent knows exactly what comes next.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: listings include byte sizes, and an html page is stored as a single file named index.html. It does not cover error behavior for a missing path or how non-text files are handled.

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

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

Two tight sentences with no filler. The primary list behavior and its return detail come first, the optional single-file mode second, and the when-to-use rule last, giving a sensible front-loaded structure.

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, and the tool is a simple two-parameter read. The description covers both modes and the html-page quirk, which is the main non-obvious fact. It could say a bit more about what happens with an invalid path, but overall it is complete for the 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 description coverage is 0%, so the description carries the burden. It does explain the key branching semantics of `path` (present = read one file's text, absent = list files) and ties `jigId` implicitly to the jig being read. It adds no format or validation detail, and the uuid nature of `jigId` is left to 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?

The description uses a specific verb and resource ("List a jig's files with their byte sizes") and describes a second, conditional mode ("with `path` read one file's text"). The two modes are clearly delineated. However, it does not distinguish jig_read from similar-sounding siblings such as jig_get, jig_open, or jig_view, so an agent must infer the difference.

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 an explicit usage rule: "Read before you edit a jig you did not just write," which tells the agent when to reach for this tool. It also implies the branch condition for `path` (omit to list, supply to read one file). It stops short of naming an alternative sibling for the cases where this tool is not the right pick.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld=false), and the description adds genuinely useful behavior: no account required, and cursor-based pagination via the returned `nextCursor`. It could say more about ordering of results or result caps, but it is well above the annotation baseline.

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 first" directive, then parameter hints, then return shape. The list of result fields is a long run-on clause, but it is informative 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?

For a zero-required-parameter search with an output schema and read-only annotations, the description covers purpose, timing, parameter edge cases, and pagination. The enumeration of return fields is partly redundant with the output schema, but nothing an agent needs to invoke it correctly is missing.

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

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

With 75% schema coverage the schema does most of the work, but the description adds semantics the schema lacks: an empty `q` means "newest" rather than an error, and `site` is illustrated as a bare host like youtube.com. `limit` is left entirely to 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?

"Search the public jigs other people published" names a specific verb (search), a specific resource (jigs), and a scope qualifier (public, other people's) that separates it from jig_list, jig_get, or jig_read. The parenthetical example query makes the intended use concrete.

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?

"Call it BEFORE building a page from scratch" gives a clear trigger condition, and the empty-`q` and `site` clauses explain the two common invocation modes. It does not name an alternative sibling (e.g. jig_list vs jig_search) or state when not to use it, so it falls short of a 5.

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

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

Annotations supply the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=false), so the description need not restate them. It does add genuinely useful context that the call originates from the open jig itself and is not agent-driven, but it never says what the call does server-side or what happens if an agent invokes it manually.

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 the identifying purpose first and the action-suppressing instruction second. Nothing is padded, though the first sentence is a touch imprecise for its length.

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

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

With annotations, a full output schema, and 100% schema coverage, the only thing the description must contribute is whether an agent should call this, and it says so plainly. What remains thin is the consequence of calling it anyway, which matters little for a tool agents are told to skip.

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 all three parameters carry meaningful schema descriptions (event, jigId tied back to jig_open/jig_list, snapshot). The description adds no parameter meaning beyond that, 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?

"Used by an open jig to report what it shows" identifies the resource (an open jig's displayed state) and the action (report), but the phrasing is loose about what is actually recorded and for whom. An agent can tell it is a state-reporting channel rather than a query, yet the purpose is only implied rather than stated as a specific effect.

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 an explicit negative instruction: "You do not need to call this," which is exactly the routing guidance an agent needs to avoid invoking an internal telemetry path. It stops short of naming an alternative tool for inspecting jig state (e.g. jig_get, jig_look), so it is clear but not fully comparative.

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

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

Annotations already mark this as a non-destructive, idempotent write, and the description adds the crucial facts annotations cannot express: the handle is public and permanent and can never be changed or released. It also discloses the failure path (taken/invalid handles are refused with a free `suggestedHandle`) and that omitting `handle` writes nothing — a dry-run mode not visible in 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 single most consequential fact (public and permanent) before any procedural guidance, then moves to the pre-call user interaction, then format rules, then edge cases. Dense but every sentence carries a distinct, load-bearing 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?

An output schema exists, so return shapes need not be explained; the description instead covers the things an agent could still get wrong — user consent, idempotent re-calls, refusal handling, and the look-only mode. Nothing needed 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%, but the description still adds meaning the schema lacks: the 2–30 character length rule, the allowed character set (lowercase letters, digits, single hyphens), that the @ is optional, and that omission means look-only. The only friction is the schema's maxLength of 40 versus the stated 30, a minor mismatch that does not obscure intent.

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 — claim the user's public handle — and immediately grounds it in concrete terms (the @name in published page links, with an example URL). It is unmistakable against siblings like jig_get or jig_update.

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 instructs to ask the user which handle they want BEFORE calling, to suggest one derived from their name, and never to choose for them. It also names the check-only invocation (no `handle`) and points to `jig_open` as the trigger for when an owner has none yet.

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

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

Beyond the annotations, the description discloses merge semantics (a null key removes it), that edits apply with each `find` matching exactly once, that the page refreshes itself within seconds (async propagation, no re-open needed), that `reset` deletes every stored row while keeping html and link, that slug changes redirect, and that newly called functions wait on user approval. The one tension is that `reset` deletes stored data while destructiveHint is false, but the description itself warns of this rather than contradicting the annotations. Concurrency and partial-failure behavior are not addressed.

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

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

Four dense sentences, front-loaded with the primary action and followed by mode-specific clarifications and the usage rule. Nothing is filler, though the nested parentheticals for edits and files make it feel packed and slightly harder to scan than a bulleted structure would be.

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 10-parameter mutation tool with nested objects, the description covers the essential decision points, the live-refresh expectation, and the collaboration path. Return values are covered by the output schema, so their absence here is fine; only edge cases such as combining `html` with `edits` or slug collisions are left unstated.

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 adds real meaning: the uniqueness constraint on each `find`, that an edit's `path` selects its file, that `state` is a merge rather than a replacement, that `files` nulls delete, and how `mergedFrom` ties to a merged `jig_pull_update` version. Some of this duplicates the schema text for `slug`, `reset`, and `files`, so it is additive rather than fully compensatory.

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 opens with a specific verb and resource ("Change a page you opened with `jig_open`") and enumerates the distinct mutation modes: merge `state`, replace `html`/`title`, targeted `edits`, project `files`. It is clearly distinguishable from siblings like `jig_open`, `jig_get`, and `jig_pull_update`, which are named as the surrounding workflow.

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 the trigger condition explicitly ("Use this whenever the user asks, in chat, for the page to show something different") and an explicit exclusion ("do not call `jig_open` again"), plus the conditional path for `mergedFrom` after `jig_pull_update` and the constraint that `reset` is used "Only when the user asks." Alternatives and when-not guidance are both present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds only that the call is tied to an open jig and is typically unnecessary — it says nothing about whether this blocks/polls, how `since` interacts with freshness, or what 'state' contains. Some added context, but thin against what a sync-style call warrants.

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

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

Two short sentences, no padding, with the disclaiming guidance front-loaded rather than buried. Slightly hurt by the negative-only framing, which leaves the reader with less actionable information than the same word count could deliver.

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 not be explained, and annotations cover the safety profile. What's missing is the tool's position in a very crowded jig_* family — how it differs from jig_get, jig_look, and jig_read is left entirely to inference, which is a real gap given 35 sibling tools.

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%, with `jigId`, `cache`, and `since` all documented in-schema including provenance ('as jig_open or jig_list returned it') and version semantics. The description adds no parameter meaning beyond that, 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?

"Used by an open jig to pick up its latest state" names the resource (jig) and a rough action (fetch latest state), but the verb is vague and the second sentence ('You do not need to call this') actively muddies whether the tool is intended for agent use or is an internal client mechanism. An agent can guess it relates to jig_open, but it can't cleanly distinguish this from jig_get, jig_look, or jig_read.

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 an explicit when-not guidance ('You do not need to call this'), which is unusual and genuinely useful, but no positive condition explaining when an agent *would* call it, and no named alternative among the many jig_* siblings. The implicit usage (client-side state sync after jig_open) must be inferred.

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

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

The annotations only declare non-read-only, non-idempotent, non-destructive, closed-world; the description adds the critical behavior the annotations do not: cost is charged up front, is non-refundable, a live price above the agreed figure is refused before any charge, and repeated identical calls cannot double-buy. It also discloses the prerequisite path via `mustFirst`. It stops short of describing what the granted IP looks like on success, though the output schema covers that.

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

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

Front-loads the why (which sites need it) before the how, and the bolded 'Never buy without asking' rule is easy to find. A few sentences are longer than needed (the opening explanation of what a dedicated IP is), but 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 paid, two-phase mutation tool, the description covers the decision path, the safety gate, the prerequisite escape hatch, and the cost model, and an output schema exists so return shape need not be restated. An agent has everything needed to call it safely.

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 adds real meaning beyond the schema: `confirmPriceCents` is the only parameter that actually triggers a purchase and must match the user-agreed price, while `another` is gated on explicit user request. It does not add detail on `country` or `termDays` beyond the schema, which already carries defaults.

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 (lease/buy) and resource (a dedicated IP) and immediately explains the motivating scenario: sites like LinkedIn marked 📍 in `get_library` that only accept sign-ins from the original address. An agent can distinguish this from sibling tools such as get_library or add_connection 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 call sequence: call with no arguments first to get a price, then call again with `confirmPriceCents` to buy. It also names the exclusion for `another: true` (only when the user asked for a second IP) and the fallback when `mustFirst` is set (give the user the link and stop).

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

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

Annotations only declare the write/non-idempotent/non-destructive profile. The description adds real behavioral context beyond them: validation is enforced against the job's inputSchema, failures are refused with a reason, and the job remains open on failure rather than being consumed. It does not say what happens to the job after a successful answer, which is the main remaining gap.

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

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

Two short sentences, front-loaded with the core action, followed by the validation and retry rule. Nothing is 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?

An output schema exists, so return values need no explanation, and the origin of jobId is stated. What is missing is the post-success lifecycle (whether the job is closed or must be re-polled), which an agent calling this tool would reasonably want to know.

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 jobId and answer are already documented, including that answer must match the job's inputSchema. The description restates the same constraint and adds the failure consequence, but contributes no new meaning about the parameters themselves; baseline 3 applies.

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

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

States a specific verb and resource: 'Answers one job from llm_poll.' The reference to llm_poll implicitly separates it from the poll-side sibling, though it does not name llm_detach or other llm_* siblings to clarify the boundary further.

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

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

Usage context is clear: it is the response half of the llm_poll loop, and the retry path is spelled out ('correct it and call again'). It does not explicitly state when not to use it or how it relates to llm_detach, but the when-to-use condition 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?

Annotations already declare non-read-only, idempotent, non-destructive. The description adds real behavioral value with 'at once' (immediate effect) and the fallback behavior ('go back to Bowmark's own model instead of waiting for this chat'). It does not say whether the chat itself is closed or what state remains afterward, which matters for a detach 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?

A single sentence with the action front-loaded and the consequence trailing. The phrasing 'open Bowmark pages' AI calls' is slightly tangled and requires a second read, but no sentence is wasted.

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

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

With an output schema present, return values need not be explained. However, the description leaves the lifecycle unclear: what happens to the chat after detachment and how this pairs with llm_answer/llm_poll for a reattach flow is unstated, which is the main missing piece for a state-changing 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?

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies the target chat is implicit context rather than an argument.

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: 'Detaches this chat at once'. The consequence clause (open Bowmark pages' AI calls revert to Bowmark's own model) distinguishes it from siblings like llm_answer and llm_poll, which serve calls rather than release them. Not a 5 because 'this chat' assumes context the agent must already hold.

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 implied usage (stop routing AI calls for Bowmark pages through this chat) is inferable from the effect described, but there is no explicit when-to-use, no precondition, and no named alternative or sequencing relative to llm_answer/llm_poll.

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

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

Beyond annotations it discloses a real side effect the annotations do not capture: calling it marks the chat as attached for 20 seconds, and attachment lapses if you stop calling. It also describes the polling semantics (returns up to 5 jobs, blocks up to waitSeconds when empty) and enumerates the job fields including leaseSeconds, which is exactly the behavioral context an agent needs to run the loop correctly.

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

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

Three dense sentences, front-loaded with what the tool does and followed by the response shape and the lifecycle/detach rule. The parenthetical job-shape list is compact, though the return fields are partly redundant with the output schema and 'so they cost nothing' is a slightly loose framing.

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 polling/lease tool with an output schema present, the description covers the loop, batching, the wait behavior, the attachment window, and how to release it. What is lightly covered is failure/staleness handling of a job whose lease expires, though leaseSeconds in the returned fields hints at it.

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

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

Schema coverage is already 100% for the single waitSeconds parameter, so the baseline is 3; the description adds meaning by clarifying the wait only applies when there are no pending jobs and that the cap is 15. It does not explain units beyond the schema's minimum, but the added conditional context pushes it above baseline.

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

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

The description states a specific verb (answer/serve AI calls) and resource (pending jobs from an open Bowmark page), and explicitly distinguishes itself from llm_answer (used to answer each job) and llm_detach (used to release the attachment). An agent can tell exactly what this tool is versus its siblings 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 gives the when (there are pending AI calls from an open Bowmark page), the loop (call repeatedly, answer each job with llm_answer), and the when-to-stop (stop calling, or call llm_detach, so calls revert to Bowmark's own model). The alternative routing to a sibling is named with the condition that selects it.

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

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

Adds substantial context beyond the annotations: the write has no effect on any website or account, costs the user nothing, does not retry the run, and is the only path to a fix. It also describes the downstream flow where an account holder may be offered a live chat handled by `support`. One minor tension: annotations mark `readOnlyHint: false` while the text says 'it changes nothing' — the description clarifies that the only effect is a stored feedback record, so this reads as clarification rather than contradiction.

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

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

Purpose is front-loaded and every substantive sentence carries novel information. The trigger enumeration is crammed into one long semicolon-chained sentence, which makes it dense to parse, but little could be cut without losing routing 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?

For a two-parameter feedback tool with an output schema and annotations already present, this covers everything an agent needs: when to call, whether to ask the user, what to write, how to handle runId, and what to do on repeat failures. Return-value behavior is covered by the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real routing logic: include `runId` when reporting on a run, omit it when the gap came from `get_library`. It also constrains the free-text `report` payload to a sentence or two 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?

The first sentence states a specific verb and resource: record what was missing, wrong, or incomplete about a Bowmark task so it can be built. It also implicitly separates this from `support` (a live chat escalation) and from `run`, which it references as the producer of the runId.

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 exhaustive trigger conditions — errors, timeouts, `partial`, empty results from a site that should have answered, untrustworthy data, and `get_library` gaps — plus the escalation path when the same task keeps failing. It also tells the agent to call it itself, in the same turn, without asking the user, which removes the main source of hesitation for an agent.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds substantially more: the one-call-at-a-time constraint with an explicit Promise.all prohibition, the idle-timeout self-close, the `needs_user` handoff behavior, and the return envelope. It does not address permission requirements for the underlying library functions or what a destructive call actually changes, leaving that to annotations alone.

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 differentiator and structured into purpose, parameters, sequencing hazard, and return shape. Dense but readable; the `run` contrast is restated twice and a few sentences could be tightened.

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 stateful, destructive, open-world tool, the description covers initiation, continuation, concurrency limits, expiry, auth handoff, and teardown. An output schema exists, yet the description's return-envelope sentence adds useful interpretive guidance on `status` values rather than merely duplicating structure.

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 schema already documents the dotted `path` example, `args` being positional, and omitting `sessionId` on the first call. The description largely restates these; its genuinely additive content is workflow sequencing rather than parameter meaning, so baseline 3 applies.

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

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

The description states a specific verb and resource ("Runs ONE library function in a Bowmark session") and immediately scopes it to stateful multi-step flows. It explicitly distinguishes itself from the sibling `run` by naming what `run` cannot do ("every run starts fresh and nothing it held survives").

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 positive use cases (booking with a texted code, multi-step cart, a form waiting on a user answer), a named alternative with the condition that selects it (`run` for stateless calls, separate sessions for parallel work), and a prerequisite workflow (`get_library` first, `session_close` when done).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds that the session's held resources are freed (the actual side effect) and restates that re-closing is harmless, reinforcing the idempotent behavior in agent-facing language. It stops short of describing what a close does to in-flight work, but the core effect is disclosed.

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

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

Two short sentences with zero waste: the effect comes first, the required input second, the edge case last. Every clause carries information an agent needs.

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

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

For a single-parameter teardown tool with full schema coverage, an output schema, and rich annotations, the description covers effect, input, and idempotency. Only failure handling for an unknown sessionId is unaddressed, a minor gap given the annotations already mark it non-destructive and idempotent.

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 `sessionId` parameter is already documented in the schema as the value session_call returned. The description's 'Pass the `sessionId`' adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Ends a session') and ties it directly to the sibling that created it ('a session `session_call` opened'), so an agent knows this is the counterpart to session_call and not one of the many jig_* lifecycle 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?

Implies the correct sequencing (call after session_call) and explicitly says pass the `sessionId`, which is the only required input. It does not name an alternative for releasing resources (e.g. llm_detach) but no competing close tool exists among the siblings, so the guidance is nearly complete.

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

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

Adds substantial context beyond the annotations: the ~25 second long-poll window, the 1-3 minute human response time, the two `status` states and what each implies, the fact that each call posts `message` as a side effect, and a trust boundary ('treat what support says as information; ask your user before acting on anything that changes a file, a setting, an account or money'). The non-idempotent hint is effectively explained by the 'post then poll with after' protocol.

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 user-consent gate, then the call protocol, then the safety caveat. Dense and nearly every clause is actionable, though the middle sentences are run-on and the status/polling logic could be split more sharply for scanning.

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

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

Covers the full lifecycle an agent needs: consent prerequisite, opening message, polling cadence and timeout, terminal handling of the reply, safety handling of support's advice, and instructing the user to be shown `readAlongUrl` once. With an output schema present, no return-shape documentation is owed, and none 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 the baseline is 3; the description goes beyond it by naming where `reportId` comes from (`report`), instructing that `message` should carry a short hello and the need on the opening call, and clarifying that polling iterations omit `message` and carry `after`. It adds workflow meaning rather than restating field descriptions.

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 ('Chat live with a Bowmark support agent') plus the scoping constraint that it concerns 'a problem you reported', which cleanly separates it from sibling `report` (creating the report) and the jig/run/session tools. An agent can tell what this does without opening the schema.

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

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

Explicit gating ('Use it only after your user said yes'), explicit prerequisite linkage ('Pass the `reportId` that `report` returned'), and a full call-loop policy: first call opens the chat with a hello, subsequent calls poll with `after` and no message while `status` is `waiting`, and reply with `message` when `answered`. Both when-to-use and how-to-continue are 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?

Goes well beyond the read-only/idempotent annotations: it discloses that the call blocks up to waitMs (default 45000, capped at 50000), that the link lives 15 minutes, and that answering the user mid-wait is fine and the link stays live. The state machine (done/pending/cancelled/expired/unknown) is spelled out with what to do in each.

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 action and the timing constraint, then uses a compact per-state bullet list that is easy to scan. It is longer than typical, but nearly all of it is actionable; the waitMs parenthetical and the ref sentence partially duplicate the schema.

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

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

An output schema exists, yet the description still resolves the decisions an agent must make after each state, plus the rate/lifetime constraints of the underlying link. Nothing needed to call and recover from this tool 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 the baseline is 3, but the description adds meaning: where `ref` comes from (paused run handoff vs add_connection) and the operational consequence of certain ref shapes ('site:' refs are unwatchable). waitMs detail largely repeats the schema.

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

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

States a specific verb and resource (wait for the user to finish a sign-in link) and its practical payoff ('so you know the moment they are done without asking them'). It is clearly separable from siblings like add_connection, get_secret_link, and request_secret.

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 timing guidance ('Call it right after you give the user the link, in the same turn'), tells the agent to write the link first, and prescribes a different action per returned state. It also names the exclusion case: a ref starting `site:` cannot be watched.

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