BrightLocal by Cotlet

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

Annotations already establish readOnly, idempotent, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable context: "Free, no browser session" tells the agent this call consumes no Cloud Browser session and costs nothing, which matters when budgeting browser steps. It does not say how large the returned guide is or whether it is cached, a minor 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?

The core instruction ("Call it before the first browser step in an app") is a short, high-value sentence, but the opening sentence is an overlong list of return contents that is hard to parse on first read. The framing sentence could be moved ahead of the enumeration so the actionable guidance is truly 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?

With no output schema, the description carries the burden of explaining what comes back, and it does so: browser selection, sign-in link, step-by-step method, screens/menus/actions, notes, and dedicated tools. Combined with the two documented parameters and full annotation coverage, an agent has enough to invoke this correctly before its first browser step.

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 both `app` (name or Cotlet slug, default BrightLocal) and `task` documented in the schema itself, so the baseline is 3. The description references "which browser to use for this workspace" and "the app's dedicated tools," which hints at what `app` unlocks, but it adds no syntax or formatting guidance for `task` beyond what the schema states.

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 resource (a per-app operating guide covering browser choice, sign-in link, method, screens, menus, actions, notes, and dedicated tools) retrieved from Cotlet's Cloud Browser toolset. It implicitly differentiates itself from the cotlet_browser_* action tools by being the pre-flight guide, though the verb is buried inside a long noun phrase rather than stated up front.

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 timing guidance is given: "Call it before the first browser step in an app," which is exactly the routing signal an agent needs against the many cotlet_browser_* siblings. It also covers scope ("Works for any web app; one outside Cotlet's catalog gets the general method"). It stops short of naming an alternative tool (e.g., cotlet_apps for discovery), so no exclusions 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description only has to add context, and it does: no cost ('Free') and an authentication requirement (API key or sign-in). It also discloses the shape of the result content (per-app connection state plus the one remedial step and console link), which is meaningful 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?

It is a single sentence plus two short fragments, so nothing is truly wasted, but the main sentence is heavily nested with parentheticals and a colon-list, making it harder to parse than necessary. The cost and auth facts land at the end rather than being surfaced as a distinct, scannable clause.

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 must convey what comes back, and it does — per-app status, the one required user action, and a console link. Cost and credential requirements are also covered. The only omission is any relationship to the sibling cotlet_app_guide or to the cotlet_browser_* tools that would act on the reported state.

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 optional 'app' filter is documented in the schema with an example ('skool'), so the schema carries the load. The description never mentions the filtering capability at all, which is a missed opportunity but not a semantic gap given full coverage. 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 names the resource (the workspace's apps) and states exactly what is returned per app: the Cloud Browser account state and the single next step with a console link. The three enumerated states (connected, signed out, signed in but not connected) make the scope concrete. It does not, however, distinguish itself from the sibling cotlet_app_guide, which an agent could easily confuse with this list.

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 and no routing to or away from cotlet_app_guide or the browser tools. The only usage-adjacent content is the prerequisite 'Needs the user's Cotlet API key or sign-in' and the cost note 'Free', which tells the agent how to call it but not when to prefer it over alternatives.

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 destructive, non-idempotent, open-world behavior, so the bar is lower; the description still adds real value by explaining the post-click return payload (elements and text in view, same numbering), the no-change signal, and the refusal policy for payment and auth surfaces. It does not cover what happens when an element is missing or off-screen, or how dialogs are surfaced.

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

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

Front-loaded with the core action and target, then modifiers, then return behavior, then safety refusals — a sensible priority order with no filler. The telegraphic style ('Answers the page after it') is compact but slightly oblique.

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 seven optional parameters, no output schema and destructive annotations, the description does the heavy lifting on return shape and edge cases (new tabs, unchanged page, refused clicks). Minor gaps remain around element resolution failures and dialog interception, which the schema covers only partially.

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 every parameter including the undocumented-in-description `dialog` and `dialog_text` is already explained. The description adds only a light framing of element-vs-coordinate mutual exclusivity and the double/right-click shortcuts, which largely restate 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 (clicks) plus the exact targets (element number or x/y point) and the modifier variants (double, button: right). It is unmistakably distinct from siblings like cotlet_browser_hover, cotlet_browser_drag, cotlet_browser_press and cotlet_browser_select.

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 clear usage context plus an explicit when-not: pay/buy buttons and sign-in/account pages are refused, and new-tab links are redirected into the current tab. It does not name alternative tools (e.g. hover vs click), so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: it discloses that cookies are preserved and the browser 'sleeps' (state is not destroyed, consistent with destructiveHint=false), that the per-minute billing stops, and what the response reports. Cost and state-retention details are exactly the operational context annotations cannot convey.

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

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

A single compact sentence with the action front-loaded, followed by the state and billing consequences and the return value. No redundant restatement of the title or annotations.

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

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

With no parameters, no output schema, and simple semantics, the description covers everything an agent needs: the trigger, the state outcome, the billing effect, and the shape of the response (minutes and credits). Nothing material 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?

There are zero parameters, so there is nothing for the description to disambiguate; the baseline applies. It correctly implies no inputs are needed to close the session.

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 ('Ends the browser session') and names the triggering condition ('when the task is done'), which cleanly separates it from the sibling cotlet_browser_open and the other browser_* action 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?

Gives a clear usage condition ('when the task is done'), which is enough to select it over the browser_* interaction tools. It does not explicitly say when NOT to close (e.g. mid-workflow with pending state) or name cotlet_browser_open as the counterpart, so it falls short of full when/when-not guidance.

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

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

Annotations already declare openWorld, non-idempotent and destructive, so the bar is lower; the description still adds real behavioral facts the annotations do not carry, namely that the returned link is valid only 15 minutes and that CSV/JSON/other text files additionally come back as text. It does not explain why a download is flagged destructive or what happens to previously returned links/files, so it stops short of fully closing the 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?

A single dense sentence, front-loaded with the action and then the result payload; nothing is redundant. The phrasing ('answers its name, type, size and a link valid 15 minutes') is slightly compressed and grammatically loose, which costs a point on readability.

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 correctly takes on the burden of describing the return payload (name, type, size, 15-minute link, text body for text formats), which is the key thing an agent needs. Gaps remain around size limits, binary handling, and whether `element` and `url` are mutually exclusive, but nothing essential to calling it is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds only modest meaning, clarifying that `element` refers to a download link or button and that `url` is opened to start the download, without expanding on the element numbering or exclusivity of the two inputs.

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 ('Gets the file that clicking element ... or opening url starts') and enumerates what is returned (name, type, size, expiring link, text for text formats). It is clearly the download counterpart to cotlet_browser_upload and distinct from click/navigate, though it never names a sibling 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 describing the triggering action: use it when a click on a download link/button or opening a URL starts a download. There is no explicit when-not guidance, no mention of preferring cotlet_browser_click or cotlet_browser_read when no download is triggered, and no prerequisites stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description's job is to add context, and it does: "Answers the page after it: the elements and text in view, with the same numbers" tells the agent the call returns a fresh page read with stable element numbering, which prevents a redundant cotlet_browser_read follow-up. It does not disclose drag mechanics such as press-move-release timing, whether it waits for animations, or what happens if the drop misses a target, so it is valuable but not 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?

Two sentences, front-loaded with the action and its accepted endpoint forms, then the return behavior. The colon-list of examples does real disambiguating work rather than padding, and there is no redundant restatement of the title or name.

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 correctly covers the return value (elements and text in view with matching numbers), and the destructive/open-world annotations cover risk. For a nested-object, drag-and-drop tool the remaining gaps are edge behavior (invalid drop targets, drag during navigation, whether the page read reflects post-animation state), which are meaningful but secondary.

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%, including per-field notes distinguishing element numbers from screenshot pixels and documenting the dialog/dialog_text enum, so the schema carries the parameter burden and baseline 3 applies. The description reinforces that "from" and "to" each accept an element or a point, but adds no syntax, format, or interaction detail beyond what the schema already states.

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?

"Drags from one element or point to another" names a specific verb and both endpoint forms, and the three examples (card between columns, board piece, slider handle) make the operation concrete. Against siblings like cotlet_browser_click, cotlet_browser_hover and cotlet_browser_press, the verb itself carves out a distinct action, so an agent can select it 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?

The example scenarios (reordering a card, moving a board piece, sliding a handle) give a clear sense of the situations this tool is for, which is real usage context rather than a bare restatement. It stops short of explicit exclusions or pointing at alternatives such as cotlet_browser_click for a simple press, so it lands at clear-context-without-routing rather than full when/when-not 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?

Adds substantial behavior beyond the annotations: sandbox limits (no requests, clicks, submits, cookie or storage access) and the [hidden by Cotlet] redaction on filled fields, which an agent would otherwise only discover by failing. It does not address the destructiveHint=true / readOnlyHint=false profile, i.e. what happens if the script mutates page state, leaving a mild tension with the 'extract, don't act' framing, though nothing is outright contradicted.

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 capability, then the use case, then the hard limits, then a one-line example — no filler sentences. The 20000-character limit and other mechanical details are correctly left to 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?

With no output schema, the description carries the return contract and does so adequately by declaring JSON-serialized results. It omits failure behavior such as timeouts, thrown exceptions, or oversized return values, which matter for an arbitrary-script tool, so it falls just short of fully 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 100% and already documents the single 'script' parameter, so the baseline is 3. The description earns an extra point by showing a concrete function-body example and clarifying the return path ('answers what it returns, as JSON'), which the terse schema line 'A function body that returns' does not convey.

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

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

States a specific verb and resource (runs a JavaScript function body on the page) plus the return contract (JSON), and distinguishes itself from the action-oriented siblings by saying 'act with the other tools.' An agent can tell this apart from cotlet_browser_read or cotlet_browser_click without opening any schema.

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

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

Gives an explicit when-to-use case ('extract data the page holds (a table, a list, attributes)') and routes state-changing work to other tools. It stops short of naming the closest alternatives, e.g. when cotlet_browser_read or cotlet_browser_find suffices, which would remove the remaining ambiguity about choosing evaluation over simpler extraction tools.

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 a destructive, non-idempotent, open-world write, and the description adds new behavior: it stops at the first failing field, names the fields already filled (partial-state semantics critical for a destructive tool), and never submits. It stops short of explaining why it is flagged destructive or what side effects a fill can trigger, such as conditional fields appearing.

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 tight sentences, front-loaded with what the tool does before the failure and submission caveats. The closing line ('Answers the page after it: the elements and text in view, with the same numbers') is awkwardly worded but still conveys the return shape and element-number continuity.

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 correctly explains the return value as a page read with contiguous element numbers and covers the critical submit/no-submit distinction. The gap is risk context: nothing tells the agent a fill can irreversibly alter page state or which forms are inappropriate to auto-fill.

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

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

Schema coverage is 100%, so the schema carries the parameter documentation and the baseline is 3. The description adds useful mapping semantics — text fields take text, drop-downs an option label, checkboxes/radios/switches true or false — slightly beyond the schema's terser 'Text, option, or true/false', but dialog and dialog_text are 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?

States a specific verb and resource ('Fills several fields in one step') and enumerates the widget types handled. It does not name the sibling tools it supersedes (cotlet_browser_type, cotlet_browser_select), so differentiation is inferred from 'several fields in one step' 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?

The tail gives real routing guidance: 'Does not send the form: click its button after', pointing the agent to cotlet_browser_click for submission. It implies batch filling replaces per-field typing but never states when a single-field sibling is preferable or what happens with a stale element number.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: matching spans iframes ('frames included') and results include element numbers plus each matching text line, which is what an agent needs to decide whether this beats a full read.

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

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

Two sentences, zero redundancy, front-loaded with the core action before the routing advice. Every clause carries information an agent would otherwise have to infer.

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 usefully sketches the return shape (element numbers and matched text lines) and discloses cross-frame scope. What is missing is minor: behavior on zero matches, result caps, or whether hidden elements are included.

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%, with `text` documented as 'Words to look for, any case' and `kind` documented with an enum and default, so the baseline is 3. The description adds a little framing about matching against labels and text lines, but does not explain the `kind` filter's effect on results, so it does not exceed the schema meaningfully.

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 scope: finds `text` across the whole current page, 'frames included', and describes both what is matched (element labels and text lines) and what is returned (element numbers). This is clearly distinct from cotlet_browser_read and cotlet_browser_scroll, which it implicitly contrasts 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?

Gives a concrete usage rule: 'Use it instead of reading or scrolling a long page for one thing,' which tells the agent when this tool beats its closest siblings. It stops short of naming the sibling tools directly or stating when-not to use it (e.g., for structural exploration), so it is clear but not exhaustive.

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 read-only, idempotent, open-world and non-destructive, so the bar is lower; the description still adds real value by disclosing that the call returns the page state afterward ('the elements and text in view, with the same numbers'), which is important since there is no output schema. It does not explain what happens if no target is supplied or whether the pointer moves away.

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 the action first and the return behavior second. The phrase 'with the same numbers' is slightly cryptic but refers back to element numbering, so 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?

For a zero-required-parameter, non-destructive hover tool this is mostly adequate, and the absence of an output schema is partly compensated by the return-value sentence. Gaps remain: no default targeting behavior when no argument is given, and only a vague sketch of what the returned page answer contains.

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, and the description adds the element-or-point framing that tells the agent the three parameters form two mutually exclusive targeting modes. It does not address defaults or what happens when all three are omitted, which the schema also leaves open.

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 target: rests the pointer on an element or a point, and names concrete outcomes (hover menu, tooltip, preview). That is far more informative than the title 'Point at the page' and distinguishes it from cotlet_browser_click by implication (hover, not activate), 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?

Saying it opens hover menus, tooltips or previews implies when to reach for it, but there is no explicit when-not guidance and no pointer to cotlet_browser_click for actual activation. The agent must infer the click-vs-hover boundary itself.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds behavior the annotations do not: that the step returns the resulting page state (elements and text in view). It omits whether navigation blocks on load, what happens on timeout or failed load, and what the 'same numbers' refer to, leaving some behavioral gaps.

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 primary action front-loaded and no filler. The closing clause 'with the same numbers' is cryptic and costs clarity rather than words, which keeps it just below top marks.

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 does carry the burden of explaining the return value, and it does so only vaguely ('the elements and text in view, with the same numbers') without defining the numbering scheme or error behavior. For an open-world navigation tool that can trigger native dialogs, more on failure modes and load semantics would be needed for full completeness.

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 `url`, `dialog`, `history`, and `dialog_text` are already fully documented, including enum values and dialog defaults. The description restates only `url` and `history` and adds nothing about `dialog`/`dialog_text` semantics, so it does not exceed the baseline.

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

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

States a specific verb and resource ('Opens `url` in the current tab') plus the alternate mode ('goes `history` back or forward'), which is clearly navigation rather than the sibling `cotlet_browser_open`. The 'current tab' phrasing implicitly separates it from opening a new browser context, but no sibling is named explicitly, so an agent must infer the distinction.

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 mechanics: supply `url` to navigate, `history` to move within the session. There is no explicit guidance on when to prefer `cotlet_browser_open` (new tab/session) versus this tool, nor when to follow a navigation with `cotlet_browser_read` instead of relying on the returned snapshot.

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 context beyond the annotations: this is a real Chrome session already authenticated as the user, it is restricted to BrightLocal pages, and it returns the visible page elements and text with stable reference numbers (important since there is no output schema). The phrase 'with the same numbers' is opaque and the description does not mention session lifetime or cleanup (cotlet_browser_close) for a non-idempotent 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 tight sentences, front-loaded with the action and the imperative 'Call it first.' No redundant restatement of the title or schema, and 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?

Given one optional parameter, no output schema, and annotations already covering the safety profile, the description covers authentication state, URL restriction, and return shape. It omits session persistence/cleanup and error behavior, which are the remaining things an agent would need for reliable orchestration.

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 earns above that by adding a real constraint the schema lacks — only BrightLocal pages may be opened, despite the schema describing a generic public http/https URI. It stops short of saying what happens if a non-BrightLocal URL is passed.

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: starts the user's BrightLocal Cloud Browser (real Chrome on Cotlet, signed in as the user) and opens `url`. The parenthetical scopes it against BrightLocal native tools, but it never distinguishes itself from the sibling cotlet_browser_navigate, which an agent could easily mistake for the same action.

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 sequencing ('Call it first') and an explicit boundary ('use it for what the BrightLocal tools do not cover'). It does not name cotlet_browser_navigate or cotlet_browser_close as alternatives, so the when-not case for overlapping browser siblings is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotence, so the safety profile is covered. The description adds genuinely non-structured behavior: the key goes to whatever element currently has focus, and the call returns the page state afterward ("the elements and text in view, with the same numbers"), which tells the agent it can chain a read directly after the press. It does not warn that a press may submit data irreversibly, but the annotations carry 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?

Two tight sentences: the first states the action and its concrete uses, the second states the result. Nothing is wasted. "With the same numbers" is slightly opaque to an agent that has not read the sibling read/find tools, but it is a useful cross-reference 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?

There is no output schema, and the description compensates by stating what comes back (visible elements and text, same numbering). Dialog handling and repeat limits live in the fully documented schema, and destructive/open-world behavior is carried by annotations. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline would be 3; the description exceeds it by mapping key choices to intent (Enter sends, Tab advances focus, Escape closes, arrows navigate lists/sliders, a single character triggers a shortcut), which is meaning beyond the enum listing. The dialog, dialog_text and repeat parameters are left entirely to the schema, which limits it to a 4.

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 ("presses a key on the focused element") and enumerates concrete intents (Enter to send, Tab to the next field, Escape to close a pop-up, arrows in a list or slider, single-character shortcuts), so the agent knows exactly what the tool does. It never names a sibling like cotlet_browser_type or cotlet_browser_click, so the boundary with typing text versus pressing discrete keys is left to inference.

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?

Several clear when-to-use contexts are supplied — submitting a form, moving focus, dismissing a pop-up, stepping through a list or slider, triggering a site shortcut. There are no explicit exclusions or named alternatives (e.g. 'to enter text, use cotlet_browser_type'), which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the description's added value is in the details it supplies: the 20,000-character cap, that open dialogs are listed first, and that field values, cookies and storage are never returned. The one omission is what an agent should do when the cap truncates the page — there is no guidance on continuing past 20k characters.

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

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

Two sentences, front-loaded with the primary behavior and return payload, then the usage rule and the exclusions. Every clause carries information; 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 no output schema, the description does the work of describing the return shape (text plus a numbered control list) and the privacy exclusions, which is adequate for a one-parameter read tool. The gap is the truncated-content path: nothing tells the agent how to read beyond the 20,000-character limit.

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% for the single `element` parameter, so the baseline is 3. The description adds only a parenthetical gloss on what an element can be ("a dialog, a form, a list"), which is mildly helpful but largely restates the schema's "Read only inside this element."

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 whole current page: its text (up to 20,000 characters) and a numbered list of its links, buttons, fields and other controls" names a specific verb and resource and enumerates the exact return contents. It also distinguishes this full-page read from the narrower `element` mode and, implicitly, from capture-style siblings like screenshot or find.

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

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

"Use it on a new page or when a step's answer is not enough" gives an explicit trigger, and the `element` clause states the alternative and its scope. It stops short of routing against other siblings such as cotlet_browser_find, cotlet_browser_evaluate or cotlet_browser_screenshot, which an agent may also consider for inspecting a page.

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, open-world, so safety is covered. The description adds genuinely useful behavior beyond that: the output is a JPEG, and it captures only the *visible* part of the page (viewport, not full page), which an agent needs to know before attempting coordinate clicks.

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 what is returned front-loaded before the usage guidance. No filler or repetition of annotation facts.

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 parameterless, no-output-schema tool, this covers the essentials: format, viewport limitation, and how to consume the result. Minor gaps remain, such as whether scrolling (cotlet_browser_scroll) is needed to see the rest of the page and any image-size/compression caveats.

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

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

The tool takes zero parameters, so the baseline is 4. The mention of x/y image coordinates is not a parameter of this tool but usefully explains how this tool's output feeds the click/drag siblings.

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 precisely what comes back: a JPEG of the visible portion of the page. That implicitly distinguishes it from the text-oriented cotlet_browser_read, though it never names that sibling or uses an explicit verb like 'capture a screenshot'.

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 concrete when-to-use guidance ('boards, canvases, maps, charts and layout that the text does not show') and a follow-on workflow (click or drag using image x/y). It does not explicitly exclude text-only checks or point to cotlet_browser_read as the alternative, so it stops short of a full when/when-not statement.

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, idempotent, non-destructive, open world), so the bar is lower; the description still adds real value by disclosing the lazy-load side effect and by describing the response ('the elements and text in view, with the same numbers'), which compensates for the missing output schema. It leaves undocumented what happens when conflicting parameters are supplied together (e.g. element plus direction and screens).

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 mechanism ('mouse wheel'), then ordered by mode, then the return note — a logical progression with no filler sentences. The telegraphic, backtick-heavy phrasing is dense but each clause carries information, so it stays readable rather than 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 four-parameter, all-optional tool with no output schema, the description covers what it does, its side effects, and roughly what comes back. Remaining gaps are behavioral edge cases (precedence between element and direction/screens, what the shared numbering refers to) rather than core information an agent needs to invoke 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 100%, so baseline is 3, but the description genuinely adds combinatorial meaning the schema does not: which parameter pairs go together (screens qualifies down/up; element selects a scroll-until mode; inside targets a container instead of the page). The cryptic phrase 'with the same numbers' hints at a shared element-numbering convention without explaining it, keeping this just short of 5.

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

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

Opens with a specific verb and resource ('Scrolls with the mouse wheel') and enumerates the four supported modes (down/up by screens, top/bottom, until element in view, inside a container), which an agent can map directly onto the enum. It does not explicitly name sibling tools (e.g. cotlet_browser_read, cotlet_browser_wait) or state how it differs from them, so it stops short of full sibling differentiation.

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?

'Content that loads on scroll appears' implies the main motivating use case (lazy-loaded or infinite-scroll content), but the description never states when to choose scroll over cotlet_browser_read, cotlet_browser_wait, or cotlet_browser_find. No exclusions or prerequisites (e.g. a page must already be open) are given, so usage is only implied.

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 the full risk profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, non-idempotent), so the description needn't restate safety. What it does add is genuinely useful: 'Answers the page after it: the elements and text in view, with the same numbers' discloses the return shape and that element numbering is stable across steps, which matters because there is no output schema. It does not say whether selection waits for navigation or submits a form, which is the main residual risk for a destructive browser step.

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 core action, then the exception case, then the return behavior. No filler, and the numbered-element contract is stated once without repetition.

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

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

With no output schema, the description usefully covers the return value, and the dialog parameters are fully documented in the schema. The remaining gap is timing/side effects – whether the step waits for load and whether a selection can submit or navigate – but for a single-element browser action this is close to 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 100%, so baseline would be 3, but the description earns above baseline by disambiguating `option`, whose schema text is merely 'The option.' – it clarifies that either the visible label or the underlying value is accepted. It also reinforces that `element` is the number from the previous step's answer, tying parameters to the read/select numbering loop.

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 (chooses) and a specific resource (an option in drop-down `element`), and the parenthetical 'its label as listed, or its value' pins down what an option is. It is clearly distinguishable from cotlet_browser_click only indirectly, via the 'home-made drop-down' caveat rather than an explicit contrast.

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 real branch condition: use this for a native drop-down, but for a home-made drop-down 'click it, then click the option' – effectively routing the agent to cotlet_browser_click. It stops short of naming that sibling or stating what happens when the element is not a list at all.

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 destructive/open-world/non-idempotent, and the description earns extra credit on top: it says existing content is replaced, refuses sensitive fields, defines tab/newline interpretation inside `text`, and states the page is re-read afterward. That is real behavioral context an agent cannot get from the 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 behavior and no filler sentences; every clause adds an actionable fact. It is densely packed, though — clauses like 'there a tab in `text` presses Tab and a line break Enter' take effort to parse, costing a bit of readability.

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

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

With no output schema, the description still tells the agent the call answers with the page's elements and text using the same numbering — critical for continuing a numbered-element workflow. Combined with the sensitive-field refusal and dialog behavior, nothing essential is missing for a 6-parameter mutating tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: `element` omitted means type at focus, `submit` means Enter, and tabs/line breaks in `text` become key presses so one call can fill a table. Only `dialog`/`dialog_text`/`slowly` are 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?

States a specific verb and resource ('Types `text` into field `element`, replacing what it held') and immediately distinguishes scope from the sibling `fill_form`. The focus-based mode is named explicitly, so an agent can tell exactly what this tool does versus fill_form or press.

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 routing: several fields → fill_form; no element → types at focus; spreadsheet cells and editors that don't number reads → click first. It also flags exclusions (password/card/one-time-code fields are refused), which is a rare and valuable when-not-to-use clause.

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 destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is covered. The description adds genuinely new behavior: the 10-file and 20 MB caps, the two accepted file-reference shapes, and that it returns the page state afterward ("the elements and text in view, with the same numbers"). It does not say what happens on partial failure or oversized files, which is the 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?

The action leads, followed by accepted file shapes, limits, and return behavior — a sensible order with no filler sentences. The dense colon/semicolon packing makes it read as one long clause chain, though nothing is strictly 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 no output schema, the description usefully describes the return value (page elements and text with consistent numbering) and supplies size/count limits, which is most of what an agent needs for a browser file-input tool. Missing pieces are error handling and any prerequisite about the file input being present on the current page.

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 the schema cannot express: the 20 MB per-file limit (only maxItems=10 appears in the schema) and the oral-form distinction between a public `url` and a Cotlet `file_id`. The `element` numbering hint is already in the schema, so it is repeated rather than added.

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 concrete verb and target ("Puts files into file field or upload button `element`"), which tells an agent exactly which page control is being acted on. It does not name the sibling `cotlet_upload_file`, which is the natural confusion point since the `file_id` form implies that tool runs first; only the phrase "a file uploaded to Cotlet" hints at the ordering.

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: files must already exist as a public URL or a prior Cotlet upload, and the `element` must come from the last read/step answer. There is no explicit when-to-use / when-not-to-use guidance and no pointer to `cotlet_upload_file` for the upload-to-Cotlet step or to `cotlet_browser_read` for refreshing element numbers.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description usefully discloses that the call also returns the page state afterwards — a non-obvious side effect — but omits the critical behavior on timeout: it says it 'says whether the text appeared,' yet not whether a miss raises an error or returns normally.

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

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

Dense and front-loaded, with the timing constraints packed parenthetically rather than in a separate paragraph. The closing phrase 'with the same numbers' is cryptic — it likely refers to another tool's element numbering without naming it, which forces a guess.

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 full burden of explaining returns, and it does so only vaguely ('the elements and text in view, with the same numbers'). The timeout-failure semantics are unaddressed, which for a wait tool is the single most operationally important detail.

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 schema text is nearly content-free ('At most.'), so the description genuinely adds meaning: default 5 seconds, ceiling of 20, and that `text` is optional so the timeout can be used alone. It does not explain units or resolution beyond seconds, but that is minor.

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 ('Waits until `text` shows on the page') plus its two modes (text+timeout, or timeout only), which distinguishes it cleanly from polling-free siblings like cotlet_browser_read. It never names a sibling tool, so an agent must infer the boundary from the phrase 'for results that load slowly'.

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?

'For results that load slowly' gives a clear triggering condition for using this instead of reading immediately. It stops short of explicit when-not guidance (e.g., don't wait if content is already present, pair with cotlet_browser_find for lookups), leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes the status vocabulary and the polling context, but says nothing about behavior for an unknown or expired call_id, retention window, or whether repeated polling is rate-limited.

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 resource and key, with the status set inlined rather than padded into separate sentences. The trailing 'answered with status pending or running' is slightly awkward phrasing but earns its place as scoping 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 one-parameter read tool with no output schema, the description supplies the crucial return-value information (the full status enum) that the structured fields omit. Only minor gaps remain, such as what accompanies the status in the response.

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 with 100% schema description coverage, so the schema already carries the semantics. The description's 'by its call_id' merely restates the schema and adds no format or sourcing detail (e.g. where the call_id came from).

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

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

States a specific resource (an earlier Cotlet call) and a specific retrieval (its status, keyed by call_id), and enumerates every terminal and intermediate state so the agent knows exactly what it will get back. No sibling tool overlaps this resource, so the lack of an explicit 'not for X' does not create ambiguity.

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 closing clause scopes it to calls whose prior response was pending or running, which effectively tells the agent this is a polling tool rather than a general history lookup. It stops short of naming an alternative or saying what to do once a terminal status is reached.

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: reports promise nothing, so the agent must tell the user it was sent and never that something will be built or fixed, and must never include passwords or tokens. It also states an auth requirement (Cotlet API key or sign-in). Minor friction remains between 'a missing dedicated tool is not a problem to report' and the schema's missing_feature enum covering a missing tool step, which an agent may have to reconcile on its own.

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 and nearly waste-free, with each sentence carrying a distinct rule (what to report, what not to report, what to promise, what never to include, auth). The opening sentence runs long with an embedded list, which slightly slows the scan.

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 7-parameter submission tool with no output schema, everything an agent needs is present: report scope, kind routing, PII exclusions, auth prerequisite, and the required user-facing framing. Return values need not be explained because no output schema exists and the tool's effect is a fire-and-forget submission.

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: which content belongs in the report (the page, the step, what you saw, error text, call_id) and how kind selection maps to user-facing intent. That goes beyond the field-level descriptions rather than restating them.

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 and target ('Sends a report to the Cotlet team') and immediately enumerates the three reportable situations: failed tool, wrong data, blocking error, un-doable browser step. It is clearly distinguishable from its siblings, none of which submit reports.

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

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

Gives explicit when-to-use cases and an explicit when-not-to-use case ('A missing dedicated tool is not a problem to report: do the task in the browser'), plus a routing rule that a user-requested feature goes as feature_request. Alternative actions are named rather than implied.

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 tell us this is a non-destructive, non-open-world write; the description adds what happens beyond that: grants are granted for all apps at once, dedicated tools appear only after the user signs in via Cloud Browser, the call is free, and it requires the user's Cotlet API key or sign-in. That is substantive behavioral and prerequisite context an agent cannot get from 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?

Content is dense and front-loaded with the core action and its all-at-once scope. Sentences are colon-chained and pack multiple ideas each (cost, auth, sign-in, verification), so it reads more like a compressed spec than clean prose, but almost nothing is 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 two-parameter mutation tool with no output schema, the description covers prerequisites (API key/sign-in), cost, side effects (grant-all), and the failure boundary (access does not guarantee a task works). It does not describe what the call returns, such as per-app grant status, which is the remaining 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%, so the baseline is 3, but the description adds a meaningful detail beyond the schema: slugs must be "as listed at https://cotlet.dev/api/v1/apps," which tells the agent where valid values come from and prevents guessing. It says nothing about the optional use_case parameter, which keeps it from a 5.

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 ("Requests access to apps for the user's workspace") and anchors it to a console equivalent ("as Request access in the console"), plus the crucial scope detail that "every app is granted at once." It also implicitly separates itself from cotlet_apps (listing) and cotlet_app_guide (working in an app), so an agent can route without opening schemas.

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 states when NOT to use it: "Not needed to work in an app: the user's AI works in any web app in their Web browser with cotlet_app_guide." It further warns that granted access does not imply a task will work and directs the agent to verify in the browser, which is a concrete alternative path.

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

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

The description adds substantial behavioral detail beyond the annotations: it returns a one-time upload_url and file_id, requires an HTTP PUT to upload_url, enforces a 25 MB limit, states the URL works only once, and notes the Cotlet API key/sign-in requirement. These details are consistent with the non-read-only, non-destructive annotation profile and materially help the agent understand the workflow.

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 most important fact—what is returned and how it is used—is front-loaded in the first sentence. The remaining sentences cover upload method, size limit, one-time behavior, and auth without wasted words.

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

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

There is no output schema, and the description fully explains the return values, the upload workflow, the file size constraint, one-time URL behavior, and authentication needs. An agent has enough information to invoke and chain this tool correctly.

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

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

Schema description coverage is 100%, with both name and content_type documented with examples in the schema itself. The description does not add parameter-specific syntax or constraints beyond that, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: it returns a one-time upload_url and file_id for a local file. It also clarifies the intended use cases (an image for a post, an attachment), but it does not explicitly distinguish this helper from sibling tools such as cotlet_browser_upload.

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

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

The description gives clear usage context: call this to obtain upload_url and file_id, PUT the file to upload_url, then pass file_id to any argument that accepts a file. It does not name when-not-to-use cases or alternative tools, so it falls short of the top score.

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds genuine value beyond them: it declares the call is credit-free ('Free') and that authentication via the user's Cotlet API key or sign-in is required, which matters for failure handling. It does not say what shape/format the response takes, but the field list largely compensates.

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: the first front-loads the substantive return contents, the second carries the cost and auth facts. No filler, no restatement of the title, and 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?

There is no output schema, so the description must carry the return contract — and it does, enumerating each field the agent will receive. Combined with the required-auth note, an agent has enough to call it correctly. Only minor gaps remain, such as how failures look when the key is missing or what access-status values are possible.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Nothing in the text conflicts with the empty 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 names a concrete resource — the Cotlet account identity for this connection — and enumerates exactly what comes back (email, workspace, access status, API key/OAuth client scope, callable apps, credit balance). That is far more specific than the bare 'who am I' title. It stops short of explicitly distinguishing itself from siblings like cotlet_balance and cotlet_apps, which overlap on the balance and app-list portions of the response.

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

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

Usage context is implied rather than stated: an agent can infer this is the pre-flight identity/permission check, and 'Needs the user's Cotlet API key or sign-in' plus 'Free' tells it the prerequisites and that no credits are consumed. However there is no explicit 'call this before cotlet_apps or cotlet_balance to verify access' routing, and no stated conditions under which this tool should be skipped.

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 this is a safe, read-only, idempotent operation. The description adds meaningful behavioral context by detailing the returned coverage/score data, per-citation fields, duplicate handling, submission capability, and the default ordering. It does not discuss pagination or error behavior, but it goes well 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?

The description is front-loaded and every clause contributes useful return-value detail, which is important because no output schema exists. It is dense and could be easier to scan with structure, but it is not padded or 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?

Given that there is no output schema, the description thoroughly covers what the report contains and how the citations are ordered. With all three parameters fully documented in the schema and safety covered by annotations, an agent has enough information to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains limit, filter, and report_id. The description adds no parameter-level meaning beyond what the schema provides. It does mention default ordering, but not how the filter or limit parameters affect results.

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, 'Read', and a specific resource, 'Citation Tracker report', then states the report's scope: where the business is listed, missing, or has wrong NAP data. This clearly distinguishes the tool from the sibling report-listing tool and makes the purpose 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?

Usage is implied by the report-reading framing and by the schema note that report_id comes from list_citation_tracker_reports. However, the description itself does not explicitly say to call the list tool first or explain when to choose this tool over alternatives. The guidance is adequate but not fully explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description does add real behavioral value by disclosing the empty-state contract: a location with no profile yields `audit` as null with a `note` explaining what to set up. It stops short of covering freshness (how recent the audit run is) or whether a run is triggered on call.

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 in the first clause, followed by return contents and then the null-audit edge case in a natural order. The long parenthetical field list is dense but informative rather than redundant; only minor trimming would be possible.

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 return-value burden and does so thoroughly, including the important null/`note` branch. It is close to complete for a single-parameter read tool; only recency/staleness of the audit and whether results are cached are unaddressed.

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 one parameter at 100% schema description coverage, the schema fully documents location_id and its provenance. The description adds no constraint, format, or edge-case meaning for the parameter beyond what the schema supplies, so the baseline of 3 applies.

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

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

States a specific verb and resource: "Read a location's Google Business Profile Audit," and enumerates the audit's contents (profile data, NAP check, local ranking factors). It is clear what the tool returns, though it never names the sibling tools (e.g. get_local_search_grid_report, get_rank_tracker_report) whose output could overlap with the ranking-factor and per-keyword rank data described here.

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 guidance on when to reach for this tool versus the several adjacent report tools (get_rank_tracker_report, get_local_search_grid_report, get_location). Usage is only implied by the resource name. The single routing hint — location_id coming from list_locations — is already in the schema, not new guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: the default scope of the selected keyword/run and the important failure mode where a location without a Google Business Profile returns `report: null` with an explanatory `note`.

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 resource and its payload, then progressively narrows to the selected keyword/run and finally the null case. It is dense and mostly earned, though the long chain of clauses in the middle sentence requires a second 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?

There is no output schema, and the description compensates by enumerating the returned structure: grid metrics, average rank, per-keyword run stats, per-point ranks, and top 10 competitors. With the null-and-note edge case documented, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and each parameter already carries a description including its default, so the description only restates the default rule ("the first keyword and the latest run unless given"). It adds no format, range, or identifier-provenance detail beyond 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?

"Read a location's Local Search Grid: the Google Maps rank at each grid point, and competitors" names a specific verb and resource and enumerates the returned data. It is clearly distinct from the sibling list_local_search_grid_reports by being a single-location report, though it never explicitly names that sibling to reinforce the split.

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

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

Usage is implied rather than stated: the description gives the defaults ("the first keyword and the latest run unless given") and the GBP prerequisite case, which tells the agent how to call it. It never says when to reach for this versus list_local_search_grid_reports or get_rank_tracker_report, so the choice is left to inference from the name.

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 establish that this is a safe read-only, idempotent operation. The description adds useful context by detailing the returned business record and explaining that it is the NAP record used for citation and listing comparisons, though it does not discuss not-found behavior or permissions.

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 front-loaded and clear, but the two sentences substantially duplicate the same field list: the first names categories such as name, address, phone, and hours, while the second repeats them with more detail. It could be tightened 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?

With no output schema and a single well-documented parameter, the description adequately explains the returned record. It would be more complete with a note on missing or inaccessible locations, but the essential retrieval behavior is covered.

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

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

The input schema has 100% description coverage and already explains that location_id comes from list_locations. The description does not add meaning beyond that, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Read one location's business details,' then enumerates the returned fields. It clearly distinguishes this single-record retrieval from the sibling list_locations tool by referring to 'one location' and noting that location_id comes from list_locations.

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: use this to retrieve a single location's details, with the ID sourced from list_locations. There is no explicit when-to-use or when-not-to-use guidance, and no alternatives such as list_locations or get_gbp_audit are named for comparison.

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, idempotent, non-destructive, closed-world), so the description's job is return behavior — and it delivers: per-engine rank, previous rank, change, ranking URL, up/down/gained/lost keyword buckets, competitors tracked, and the crucial "null = not in the top 50" semantics. It does not cover edge cases like an invalid run_id or a report with only one run, which keeps 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?

A single front-loaded sentence with the core operation first, then the return shape, then the `runs` note — the semicolon-separated clauses keep it scannable despite its density. Every clause carries information, though the sentence is long enough that a reader must parse carefully.

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 must carry the return-value burden, and it does so in detail, including comparison semantics against the prior run. The remaining gap is behavioral edge cases (single-run reports, invalid run_id), which are non-trivial for a comparison-based report but do not block correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by restating the run_id default ("the latest unless run_id is given") and by explaining that `runs` enumerates every available run, which is otherwise only implied by the schema's cross-reference. No format or constraint details are added beyond that.

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

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

Opens with a specific verb+resource ("Read a Rank Tracker report") and immediately scopes the content: per-keyword positions on Google, Maps and the local pack, with changes. That distinguishes it cleanly from list_rank_tracker_reports and update_rank_tracker_keywords in the sibling set.

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: "Returns one run of the report (the latest unless run_id is given)" tells the agent the default behavior, and the routing to list_rank_tracker_reports lives in the schema, not the description. There is no explicit when-to-use vs. when-not guidance or mention of prerequisites such as the report needing at least two runs to compare.

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 and closed-world, so the safety profile is covered. The description earns credit for adding non-obvious behavior: locations lacking a Reputation Manager report (BrightLocal Grow plan) return zeros plus a note, which tells the agent how to interpret an all-zero result instead of treating it as an error.

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 and effect, then enumerates the returned metrics. The second sentence is a dense run-on list of every time window (last 30 days, this and last month, this year), which is informative but could be tightened without losing meaning.

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

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

No output schema exists, and the description compensates fully by enumerating the return shape: average rating, total reviews, per-star counts, per-site breakdown with links, and the zero-response edge case. For a single-parameter read tool this covers everything needed to call and interpret 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?

Only one parameter, documented at 100% coverage in the schema with a direct pointer to list_locations as its source, so the schema already carries the semantics. The description adds no further constraint on location_id beyond the incidental note that some locations have no reputation report; 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 ('Read a location's star rating and review counts') and scopes it as an aggregate summary 'overall and per review site', which implicitly separates it from the sibling list_reviews that returns individual reviews. It stops short of naming that sibling explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is implied by the phrasing ('Read a location's...') but there is no explicit when-to-use, when-not, or alternative-tool guidance. An agent must infer that this is for aggregate reputation metrics and not for fetching individual review text or review response workflows.

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, and closed-world behavior, so the safety profile is covered. Beyond that, the description discloses domain behavior the annotations cannot: that alerts are field-level diffs against six named external directories, that they are gated on Active Sync connections, and that new_alerts counts unseen ones — a return-field detail with no output schema to carry 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?

Three sentences, front-loaded with the verb and resource, then the definition of an alert, then the Active Sync precondition and the new_alerts note. The parenthetical field and platform lists are long but each enumerates real values an agent would otherwise have to guess, so the length earns its place.

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

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

With no output schema, the description carries the burden of explaining returns and does so partially: it defines an alert's structure and mentions new_alerts. It stops short of describing the overall response envelope (alert collection, cursor for continuation), which the 'cursor' parameter implies but the description never explains, leaving a small gap for a paginated list tool.

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

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

Schema description coverage is 100%, with both 'query' (location name search) and 'cursor' (next_cursor from previous call) fully documented in the schema, so the baseline is 3. The description implies location scoping through its talk of 'a location's listings' but adds no syntax, matching behavior, or pagination semantics for either 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?

States a specific verb and resource ('List Active Sync alerts') and then defines precisely what an alert is: a field-level mismatch between an external listing (Google Business Profile, Facebook, Bing, Apple Maps, Yelp) and the BrightLocal location data. No sibling tool covers this resource, so differentiation is not required, and an agent can tell exactly what it will get back.

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 supplies an important precondition — alerts exist only for locations with Active Sync connections — which tells the agent when results will be empty rather than broken. It does not, however, state when to prefer this tool over a broader listing tool, nor how to page through results or what to do with the cursor, leaving usage partially implied.

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 readOnly/idempotent annotations, it discloses a genuinely non-obvious behavior: location_id filters each page only after BrightLocal returns it, so a page can come back short while next_cursor keeps going, and total counts all campaigns. That post-filter pagination quirk is exactly the kind of detail an agent cannot infer from structured fields and would otherwise misread as end-of-results.

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, then row contents, then the filtering caveat in a single dense paragraph with no filler sentences. Minor redundancy in listing status values twice when the schema enum already enumerates them.

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 return-value burden and does so fully: it names every field per row, defines total versus page semantics, and warns about short pages during pagination. An agent could call this correctly without further context.

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: it explains the paging interaction of cursor with location_id post-filtering and clarifies that 'Saved' means not yet paid or submitted. Status enum values are already in the schema, so enumerating them again adds little.

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

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

States a specific verb and resource ('List Citation Builder campaigns'), then enumerates the exact row shape (location, status, payment date, listings ordered, aggregators, alerts), which makes it unmistakable against siblings like get_citation_tracker_report or list_locations.

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 through the status filter and the note that 'Saved campaigns are not paid or submitted yet', which hints at when Saved rows matter. However, it never states when to prefer this tool over the citation tracker report siblings, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: a fixed page size of 20, and the fact that location_id is applied after BrightLocal returns a page, so short pages are normal and next_cursor keeps going. It stops short of stating ordering or whether a total count is returned, 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?

The output shape is front-loaded, then pagination caveat, then the sibling handoff — a sensible order with no filler. The two parenthetical glosses on live/competitor citations are useful but make the opening sentence dense; a slightly tighter phrasing would lose nothing.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so field by field. Combined with the pagination rule and the alternative tool, an agent has everything needed to call it correctly and interpret a short page.

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 100% schema coverage the baseline would be 3, but the description adds meaning the schema does not: cursor is framed as continuing past a page that may have been shortened by post-fetch filtering, and location_id is characterized as a page-level filter rather than a server-side query. Neither insight is recoverable from "Only reports of this location."

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 ("List Citation Tracker reports") and then enumerates exactly what each row contains (location, reference, schedule, last run, live citations, competitor citations), including a definitional gloss for the two citation counts. It is immediately distinguishable from get_citation_tracker_report, which is named as the single-report counterpart.

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 routes the agent: use this tool to enumerate reports, and use get_citation_tracker_report to read one. That names the alternative and the condition that selects it, which is exactly the kind of sibling differentiation an agent needs.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the description's real contribution is the non-obvious pagination caveat: location_id is applied after BrightLocal returns a page, so pages can come back short while next_cursor continues. That is genuinely valuable behavior beyond the annotations, though rate limits or result ordering are not covered.

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?

Content is front-loaded: purpose first, then row shape, then constraints, then the sibling pointer. The column enumeration in the second sentence is dense but each item earns its place by telling the agent what it can rely on in the response. Slightly long but 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?

There is no output schema, and the description compensates by enumerating the returned fields, the pagination behavior, and the eligibility constraint that suppresses rows. An agent can call this correctly and interpret empty or short pages without further information.

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

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

Schema coverage is 100%, so both parameters are already documented; the description still adds real semantics by explaining that cursor is a continuation token from a prior call and that location_id filters post-retrieval per page rather than narrowing the server-side query. That goes beyond the one-line schema 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?

The description opens with a specific verb and resource ("List Local Search Grid reports") and enumerates the exact row contents (location, keywords, schedule, last run, status, grid size, points, average rank and change, re-run credits). It is clearly distinguished from the sibling get_local_search_grid_report, which is named as the tool for reading a single grid.

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 routes the agent explicitly to get_local_search_grid_report for reading an individual grid, and warns that locations without a Google Business Profile yield no rows. It does not spell out other conditions (e.g. use this to discover a report before fetching it), but the list-vs-read split 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioural value beyond that: a fixed 50-per-page result size, the full metric payload of the All Locations view, the `reports` availability map, and the status vocabulary including ad_hoc. It stops short of saying how many pages typically exist or whether an empty result differs from a filtered-out 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?

Purpose is front-loaded in the first clause and pagination sits at the end where it belongs. The middle metric enumeration is long and reads like a UI checklist, but each listed field is a genuine return-value contract given there is no output schema, so it largely earns its space.

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 and rich annotations, the description carries the return-shape burden and does so thoroughly: identity fields, status values, every metric, the `reports` map, and the page size. An agent can call this and interpret the result without further documentation.

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

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

Schema description coverage is 100%, so all three parameters (query, cursor, status) are already documented in the schema with an enum and a stated default. The description adds no meaning beyond that baseline — it never mentions the filters, the cursor, or what happens when status is omitted.

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

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

Opens with a specific verb+resource ('List the locations in the account') and immediately scopes it with the metrics returned, anchored to the product concept 'as on All Locations'. The plural listing scope makes it distinguishable from the single-location sibling get_location.

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 can infer this is the way to enumerate locations and that `query`/`status` narrow the set, but the description never says when to prefer this over get_location, nor when to skip it in favour of a report tool such as get_rank_tracker_report. No explicit exclusions.

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, idempotent, non-destructive, closed-world), and the description adds substantive behavior beyond them: average_google_position is null when no keyword ranks in the top 50, location_id filters post-fetch so pages can come back short while next_cursor continues, and totals count all reports rather than the filtered subset. These are exactly the non-obvious traits a caller needs before invoking and paginating.

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 content is front-loaded with purpose and row shape, then the caveats, with no filler sentences. It is dense and slightly run-on in places ('total counts all reports'), but 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?

There is no output schema, so the description carries the return-shape burden and does so fully: it lists the row fields, the null condition, and the pagination/filter interaction. Nothing material for correct invocation 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 genuine meaning: it clarifies that location_id is applied after BrightLocal returns results (affecting page size and total semantics) and that cursor must come from next_cursor on the previous call. It stops short of stating any format details beyond that, so a 4 rather than 5.

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 ('List Rank Tracker reports') and immediately enumerates the row content (location, schedule, latest run date, status, average Google position, keyword movement), which clearly separates it from the singular get_rank_tracker_report and from sibling list_* report tools. An agent can determine the output shape 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 explicitly routes the agent to the alternative: 'Read a report with get_rank_tracker_report and its location_id.' It also explains the operational condition for paginating with cursor and the caveat that location_id filtering happens after fetch, which changes how a caller should interpret a short page.

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, and the description adds substantial behavior beyond them: sort order, the full status vocabulary, the meaning of can_reply (needs a connected GBP or Facebook page), and the empty-list-plus-note outcome for locations without a Reputation Manager report. That is exactly the kind of outcome and prerequisite context annotations cannot express.

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

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

The scope and ordering are front-loaded in the first clause, and the second sentence carries the return fields and prerequisites without filler. The long parenthetical enumeration of status values is dense but earns its place by defining an otherwise opaque field.

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 usefully enumerates return fields and explains can_reply, and it covers the key prerequisite and empty-result case. The only gap is pagination behavior: it never mentions the next_cursor/limit loop, leaving that entirely to the schema field descriptions.

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 limit, cursor, rating, source and location_id are all documented in the schema itself. The description only echoes 'filter by rating and site' and adds no syntax, default, or edge-case guidance 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?

The description states a specific verb and resource ('List a location's reviews from all tracked review sites'), plus ordering ('newest first') and the fields returned. It is clearly distinguishable from get_review_summary (aggregate) and respond_to_review (write) in the sibling list 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 real usage context: filter by rating and site, and the prerequisite that the location must have a Reputation Manager report (BrightLocal Grow plan with GBP or Facebook connected), including what happens when it does not. It stops short of naming alternatives such as get_review_summary for aggregate stats or respond_to_review for replying, so there is no explicit when-not-to-use.

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

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

Goes well beyond the annotations: it discloses that a run consumes ad-hoc run credits (plus grid credits for Local Search Grid), that runs stop after a trial ends, that precondition failures are refused with a reason, and that the run is asynchronous, taking minutes. It does not address the non-idempotent/repeat-call consequence (each call spending another credit) or what the destructiveHint means for existing report data.

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 prerequisite and cost information is front-loaded and dense, but the opening two sentences are near-duplicates ('Run... now, as the Re-run button does' vs 'Starts a manual run... as the Re-run button does'), so the lead wastes space on restatement before getting to the constraints that actually matter.

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

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

For a non-idempotent, credit-consuming trigger with no output schema, the description covers cost, gating conditions, failure mode, and latency, and tells the agent to fetch the report separately afterwards. The remaining gap is what the call itself returns (e.g., a run identifier or confirmation) so the agent knows what to do between triggering and reading.

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 both parameters are documented in-schema, so the baseline is 3. The description adds some meaning by tying specific report_type values to prerequisites, but adds nothing about location_id or the remaining enum values beyond what the schema already conveys.

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 plus resource: 'Run one of a location's reports now' / 'Starts a manual run of the location's report of that type.' It distinguishes itself from the get_*_report siblings by making clear this triggers a new run rather than fetching results, though the 'as the Re-run button does' clause is stated twice without adding information.

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 preconditions per report type (local_search_grid and gbp_audit need a Google Business Profile, reputation_manager needs the Grow plan) and notes the call is refused with a reason otherwise. It also implies the follow-up path with 'read the report afterwards,' but never names the get_*_report sibling that should be used to retrieve results.

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 a destructive, non-idempotent, open-world write, so the bar is lower, and the description still adds real behavior: the text becomes publicly visible, the review is marked Manually Responded, and there is an owner-approval step. The final sentence 'Waits for the owner's approval' is useful but ambiguous about whether the call blocks, queues, or returns pending 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?

Five short sentences, front-loaded with the action and visibility, then eligibility constraints, then effects. Nothing is wasted, though the closing approval sentence is vague enough that it costs a little clarity.

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 3-parameter public mutation with no output schema, the description covers eligibility, side effects, and visibility, which is what an agent needs to decide and call. It stops short of describing what the call returns or how to confirm the reply was published versus left pending approval.

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 every parameter is already documented with type, bounds, and provenance (review_id from list_reviews, location_id from list_locations), so the description need not repeat them. It adds only the implicit constraint that review_id must resolve to a review among the location's latest 1000, which is marginal value over 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 opens with a specific verb and resource ('Post a public reply to a review on Google or Facebook') and names the platform layer (BrightLocal), which immediately separates it from read-only siblings like list_reviews or get_review_summary.

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 explicit preconditions for use: the review must have can_reply true from list_reviews, the location needs a connected Google Business Profile or Facebook page, and the review must fall within the latest 1000. That is a concrete when-to-use gate plus a pointer to the sibling that supplies review_id.

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, and the description adds real value on top: only the keyword list changes while other report settings are preserved, the 100-keyword cap, the no-duplicate rule for adds, and the timing of when new keywords receive positions. It doesn't cover failure modes such as removing keywords that aren't tracked, which matters given the destructive hint.

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?

Five short sentences, front-loaded with the core action and followed by constraints and timing. The second sentence slightly restates the first but earns its place by establishing that other settings are left untouched; overall there is little waste.

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 mutation tool with a fully documented schema and rich annotations, the description supplies the missing behavioral layer: partial-update scope, deduplication, volume limits, and when results materialize. An agent has enough to call this correctly without an 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 contributes semantics the schema cannot express: the per-report limit's practical meaning, the deduplication behavior of 'add', and the deferred-scoring consequence of both lists. This meaningfully clarifies how the two keyword arrays behave beyond their item constraints.

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 pair and resource: 'Add or remove keywords tracked by a location's Rank Tracker report.' That distinguishes it cleanly from read-only siblings like get_rank_tracker_report and list_rank_tracker_reports, and it names rerun_report as a related action.

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 makes the intended use obvious (change the tracked keyword set) and cross-references rerun_report as the way to get positions immediately rather than waiting for the scheduled run. It stops short of explicit when-not-to-use guidance or stating what happens if a location has no Rank Tracker report.

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