Wrendex

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

With no annotations, the description carries the full burden and does so: it discloses that partial work is preserved and scored, the terminal status ('cancelled'), the 409 failure mode for completed runs, and both the required token scope (WRITE) and roles (EDITOR/ADMIN/OWNER). This is unusually complete behavioral disclosure for a mutation tool.

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

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

Three tight sentences, front-loaded with the action and its effect, then error and auth constraints. Every sentence carries distinct information with no repetition of the name or 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?

For a no-output-schema, no-annotation mutation tool, the description covers effect, terminal state, error condition, and auth prerequisites. It stops short of describing the response payload or idempotency on repeat calls, but nothing critical to invoking 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 coverage is 100%, so the single crawlId parameter is structurally documented (albeit thinly as 'Path parameter crawlId.'). The description adds no format, ID-source, or usage detail beyond what the schema provides, 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+resource ('Stop an in-flight crawl run') with an explicit scope qualifier ('in-flight') that cleanly separates it from siblings like enqueue_crawl and recrawl_pages. An agent can identify the operation 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 'in-flight' qualifier and the 409-on-already-finished condition tell the agent exactly when this call will succeed versus fail, which is effectively a when-to-use guard. It does not name an alternative tool, but no sibling is a plausible substitute for stopping a run.

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

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

With no annotations, the description carries the full burden and delivers: nothing is charged until a person opens the URL, the specific 409 WORKSPACE_UNCLAIMED failure with a claimUrl, and where to check pricing. Auth requirement and no-charge semantics are stated.

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

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

Front-loads the action and return value in the first two sentences, which is well structured. It is somewhat long, and the free-credits/pricing tangent could be trimmed, but each sentence still informs the calling decision.

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?

Even without an output schema, it describes the return shape ({url, sessionId}) and covers the key edge case (unclaimed workspace -> 409 + claimUrl) plus auth. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds decision value beyond the schema by contrasting what a plan provides ('larger monthly allowance and storage') and pointing to a pricing endpoint for tier choice. It leaves per-parameter syntax 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?

Starts with a specific verb and resource: 'Create a Stripe Checkout link that subscribes the workspace to a plan.' It also states the return value ('Returns {url, sessionId}'), so the agent distinguishes it cleanly from the crawl/site siblings without opening the schema.

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

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

Gives explicit conditions: caller must be OWNER or ADMIN, the workspace must be claimed by a person first, and the link is to be handed to the workspace owner. It also notes free credits exist without a plan, implicitly framing when a plan is actually needed.

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

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

With no annotations, the description carries the full burden and does so well: it discloses idempotent behavior (returns the active run if one exists), the incremental cost model (carried-forward pages cost no credits; full mode bills every page), the required WRITE-scoped token, the EDITOR/ADMIN/OWNER role, and credit consumption. These are exactly the side-effect and auth facts an agent needs before invoking a write tool.

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

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

Four compact sentences, front-loaded with the purpose, then behavior, then auth/cost. Dense but nearly every clause earns its place; the mode sentence slightly overlaps the schema description.

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

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

Although there is no output schema, the description identifies what is returned (the queued CrawlRun, or the already-active one). Combined with auth, role, cost, and incrementality details, an agent has everything needed to invoke 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 the mode enum's description already explains incremental vs full and their billing implications, so the schema does the heavy lifting. The description's mode guidance reinforces but does not add meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (Enqueue) plus resource (recursive crawl run for a site) with clear scope, and the idempotent-return sentence clarifies it creates-or-returns a crawl run. This is readily distinguishable from read siblings (get_crawl, list_crawls) and from cancel_crawl.

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 when-to-use context: re-crawls are incremental by default, and 'Pass mode="full" to re-fetch every page' tells the agent when to override. It also explains the case where an active run is returned instead of a new one. It stops short of naming alternatives like recrawl_pages, so it isn't a full 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?

No annotations are provided, so the description carries the full behavioral burden. It hints at return content ('status and progress') but says nothing about read-only semantics, authorization requirements, or behavior when the id does not exist.

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

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

One tightly written sentence with the resource and scope front-loaded; there is no filler or redundant restatement of the 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?

For a one-parameter read tool with no output schema, the description gives minimal but sufficient framing, mentioning status and progress. It could say more about the returned shape or failure conditions, leaving a modest gap given the absence of annotations and 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?

The single parameter has 100% schema description coverage, so the baseline is 3. The description only reinforces that the id identifies the crawl run, adding nothing 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?

States a specific verb (Get), resource (a single crawl run), and scope (by id), which clearly separates it from list_crawls. It does not explicitly name any sibling, so it falls short of the 5 required for 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?

The phrase 'by id' implies the tool is for retrieving a known crawl, but it never states when to use this versus list_crawls or the crawl sub-resource tools (get_crawl_issues, get_crawl_alerts). 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?

With no annotations, the description carries the full burden and does add real behavioral context: per-target checks file one alert per target, affectedUrls holds that single URL, HTTP status lives in the message, and for HTTP_404 the pageUrl is the failing URL. That is useful non-obvious domain detail, though read-only safety, auth, and pagination caps are not otherwise characterized.

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

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

Front-loads the core purpose and return shape, then moves to filtering, in three efficient sentences with no filler. It is dense but every clause carries information.

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

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

For a 7-parameter list tool with no output schema and no annotations, the description covers the return fields and the per-target alert semantics an agent needs. It could be more complete about ordering or total counts / pagination metadata, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents page, size, type, status, severity, crawlId, and pageUrlContains. The description reinforces `type` with concrete values but adds no syntax or format 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?

States a specific verb and resource ('List individual alerts for a crawl run') and enumerates the returned fields (pageUrl, message, detail, affectedUrls). It is clear on its own, but it never distinguishes itself from the sibling alert-adjacent tools like get_crawl_issues or get_crawl_issue_summary, leaving the agent to infer the boundary between 'alerts' and 'issues'.

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 practical invocation guidance ('Pass `type` to drill into one issue type', 'Pass a filter or pagination param'), including concrete type examples. However, it offers no when-to-use/when-not-to-use framing relative to get_crawl_issues or get_crawl_issue_summary, so alternative selection 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?

No annotations are provided, so the description carries the full disclosure burden. It does add one genuinely useful behavioral rule — ignored alerts are excluded — but says nothing about permissions, pagination, or how 'severity' is computed, leaving the mutation/safety profile implicit from the verb 'Summarize'.

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 no filler; the scope, grouping, and exclusion rule all appear in the first clause set without redundancy.

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

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

For a read-only summarizer with one required parameter and no output schema, the description covers what is aggregated (issues by type and severity) and one filtering rule. It is adequate but leaves sibling disambiguation unresolved and gives no hint about result shape or volume.

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% for the single crawlId parameter, so the schema already documents the input. The description adds no format, validity, or scoping detail about crawlId 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?

States a specific verb (Summarize) and a specific resource (SEO and quality issues found in a crawl run), plus the grouping dimension. It is clear on its own, but it does not distinguish itself from the near-identical sibling get_crawl_issue_summary or from get_crawl_alerts.

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 no when-to-use guidance, no prerequisites, and never names an alternative, despite three closely related siblings (get_crawl_issue_summary, get_crawl_alerts, get_crawl). An agent must guess which of these to call.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the grouping key (type, affected URL), the special grouping for page-text checks (TITLE_TOO_LONG -> target=title, targetIsSubject=true), the null-target fallback (TITLE_MISSING), the ignored-alert default, and the pageUrls cap with direction to trust pageCount. These are non-obvious behaviors an agent would otherwise get wrong.

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?

Six information-dense sentences with the core value proposition and the sibling comparison front-loaded. Length is justified by the aggregation semantics, though it is close to the upper bound of what is useful in a single description.

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

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

For an 8-parameter aggregation tool with no output schema, the description covers grouping semantics, edge cases, filtering, ignored-alert behavior, and pagination caveats. An agent has everything needed to interpret results correctly without seeing the response shape.

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

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

Schema description coverage is 100%, so the schema already documents crawlId, page, size, type, category, severity, includeIgnored, and pageUrlContains. The description reinforces category/type selection but adds little syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific operation (rolling alerts up into unique issues) on a specific resource, ranked by reach, and explicitly contrasts the output with get_crawl_alerts' per-page emission. The agent can distinguish it from get_crawl_alerts and get_crawl_issues 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 explicit routing conditions ('Prefer this over get_crawl_alerts when answering "what should I fix first"') and names the alternatives for the cases this tool does not cover (get_crawl_alerts for the full page list, get_crawl_issues for listing categories). When-to-use and when-to-use-something-else are both present.

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

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses the per-region payload (two source locations, shared bytes, snippet) and that results are paged. It does not mention auth needs, error behavior for a non-duplicate alertId, or ordering guarantees.

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 carries the purpose and payload, the second carries the routing rationale. No filler, and the most important information (what this returns) is 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?

There is no output schema, so the description must convey return content, and it does: source locations, shared bytes, and code snippet per region, plus pagination. An agent has everything needed to call it and interpret results.

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 page, size, and alertId are already documented in the schema (including defaults and max 50). The description adds no parameter syntax or constraints 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?

States a specific verb (page through) and resource (duplicated code regions) and scopes it to two named alert types (DUPLICATE_JS_CODE, DUPLICATE_CSS_CODE). It also implicitly separates itself from the crawl-wide report, which no sibling name alone would convey.

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 this to read the actual duplicated code" gives a clear use condition and contrasts it with an alternative (the crawl-wide duplicate-code report that has no snippets). It stops short of explicit when-not-to-use or prerequisite conditions (e.g. what alert types are invalid).

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose that the result is a history series with one point per crawl, which is useful, but it says nothing about ordering, time-range limits, pagination, or what a missing/never-crawled site returns.

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

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

One short sentence, front-loaded with the verb and resource, with the clarifying parenthetical placed immediately after. Nothing is 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?

For a one-parameter read tool with no output schema, the description conveys the essential shape of the return value (a per-crawl point series). It stops short of details an agent might need to consume the result correctly, such as ordering or any date-range constraint.

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

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

Schema description coverage is 100%, so the single siteId parameter is documented by the schema itself ('Path parameter siteId.'). The description adds no format, example, or sourcing detail beyond that, which is the expected baseline when the schema does the work.

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 (Get) and resource (a site's health-score history), and the parenthetical '(one point per crawl)' pins down the granularity of the returned series. It is distinguishable from sibling read tools like get_crawl_issues or get_crawl_issue_summary, though it never names or contrasts them 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?

There is no statement of when to use this tool, when not to, or which sibling to prefer for related crawl-quality questions. The granularity note hints that it is for tracking trends over crawls, but that is inference rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It reveals that the return is configuration and metadata (a read), but says nothing about permissions, tenant/site validation, or behavior when the site does not exist.

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 no filler, correctly leading with the verb and resource. It is efficient, though almost too terse to be maximally useful.

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

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

For a simple two-parameter read tool with no output schema, the description conveys what comes back (configuration and metadata) and the tenant scope. However, with zero annotations it should say more about safe-read behavior and error semantics to be 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 description coverage is 100%, so both path parameters are documented in the schema, and the description adds only the 'within a tenant' scoping hint. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Get) and resource (a single site's configuration and metadata) with tenant scoping. It implicitly contrasts with list_sites by saying 'a single site', though it never names the 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?

No guidance on when to use this versus list_sites or other retrieval tools, and no mention of prerequisites or failure cases. Usage is only implied by the retrieval verb.

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

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

No annotations are provided, so the description carries the full burden, and it delivers the crucial behavioral fact that this creates a persistent ignore rule that suppresses the issue on future crawls rather than a one-off dismissal. It also flags the precondition that only alerts naming a URL can use target_pattern. It does not disclose permissions, idempotency, or how to reverse the rule (only implicit via the unignore_alert sibling).

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 essential instruction and the mandatory user-consult rule before the scope taxonomy, which is the right ordering. The scope explanations are dense but each clause adds discriminating information; only the parenthetical examples of alert types are slightly padded.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers purpose, scoping semantics, persistence side effects, and a hard user-consultation requirement. Remaining gaps are error/conflict behavior and the reversal path, which are minor given the sibling unignore_alert exists.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantic distinction between route_pattern (glob over the PAGE the issue was found on) and target_pattern (glob over the URL the issue is ABOUT, wherever it is linked from) with concrete examples. This disambiguates the two easily-confused enum branches beyond what the schema alone 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?

States a specific verb+resource ('Ignore an alert') and immediately qualifies it with the required scope dimension. It is trivially distinguishable from the sibling unignore_alert, and the four scope values are enumerated inline so an agent knows the shape of the call before opening the schema.

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

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

Explicitly instructs 'ALWAYS ask the user which scope they want before calling' and then explains the discriminating condition for each of the four scopes (page URL vs issue type vs glob over page vs glob over the target URL). No alternative 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?

With no annotations, the description carries full behavioral burden. It discloses only the sort order ('newest first') and omits pagination behavior, authorization requirements, result limits, and any read-only safety context.

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 no filler. Every word contributes to the tool's scope and ordering.

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

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

The tool is simple with one required parameter and full schema coverage, so the description is minimally sufficient. However, with no output schema and no annotations, it should ideally mention pagination or result-limit behavior.

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

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

Schema description coverage is 100%, so the schema already documents siteId. The phrase 'for a site' restates the parameter's purpose but adds no syntax or format 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?

States a specific verb and resource: 'List crawl runs for a site.' It also adds ordering ('newest first'). It does not explicitly distinguish itself from siblings like get_crawl, but the plural list scope is clear.

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

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

The description implies the tool lists crawl runs for a given site, but it gives no explicit when-to-use guidance, no exclusions, and no alternatives such as get_crawl or enqueue_crawl.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does not meet it. It says nothing about pagination, result caps, permission requirements, or return shape; 'List all' is the only behavioral hint and it is unelaborated.

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

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

One short, front-loaded sentence with zero filler or redundancy. Nothing in it could be removed without losing the 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 simple single-parameter list tool with full schema coverage and no output schema, the description is minimally adequate. It omits pagination and scope-limit behavior that an agent enumerating sites would reasonably need, but it is not misleading.

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 parameter with 100% schema description coverage, so the baseline of 3 applies. The phrase 'belonging to a tenant' reinforces that tenantId scopes the result set but adds no syntax, format, or constraint 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?

The description states a specific verb (List) and resource (sites) with the scoping constraint (belonging to a tenant), so the operation is unambiguous. It does not, however, distinguish itself from its closest siblings get_site (single site) or list_tenants (different resource), leaving that differentiation 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?

Usage is only implied: the agent can infer this tool is for enumerating sites under a known tenantId. There is no explicit statement of when to prefer this over get_site for a single site, nor any prerequisite or exclusion 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?

With no annotations, the description carries the full burden. It discloses the token-scoping behavior and that it takes no arguments, but does not elaborate on return format beyond ids, pagination, empty states, or explicit read-only nature (though 'List' implies it). Adequate but with clear 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?

Three sentences, front-loaded with purpose, then usage, then a zero-argument confirmation. Every sentence earns its place with no redundancy.

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

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

For a simple zero-argument list tool with no annotations or output schema, the description covers what it returns (workspaces with ids), why it matters (prerequisite for other tools), and that it takes no arguments. Minor gaps like pagination or error cases are not critical here.

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

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

Zero parameters with 100% schema coverage, so the baseline is 4. The description correctly states 'Takes no arguments', confirming there is nothing further to document.

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

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

The description states a specific verb (List) and resource (workspaces/tenants) with the access scope (your token can access) and the return content (their ids). It clearly distinguishes itself from siblings by positioning as the prerequisite entry point that provides tenantId for other 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?

Explicitly says 'Call this FIRST' and explains why: the returned tenant id is the `tenantId` argument needed by other tools like list_sites and search. This leaves no ambiguity about when and why to invoke it.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the WRITE-scoped token requirement, the ADMIN/OWNER role requirement, the cost (one crawl credit per page), the in-place health-score mutation, and that analysis is re-run. That is exactly the kind of behavioral context annotations would otherwise provide.

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

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

Three tightly written sentences, front-loaded with the core action, then the use case, then the selector heuristic, then the constraints. Every sentence earns its place with no redundancy.

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

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

For a mutation tool with no annotations and no output schema, it covers action, effect, preconditions and cost well. The remaining gap is that it does not describe what the call returns (e.g., a job/recrawl handle vs. synchronous result), which the absent output schema leaves to the description.

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

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

Schema coverage is 100%, so the schema already documents every parameter and baseline is 3. The description adds real value by explaining the selection strategy ('a summary row can cover far more pages than it lists') and the finding-vs-URL tradeoff, which the schema does not articulate.

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 with precise scope: re-crawl only the pages affected by one finding, re-run that crawl's analysis, and update the health score in place. It clearly distinguishes itself from siblings like enqueue_crawl (full crawl) and get_crawl (read-only), 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?

It gives clear context ('Use after fixing an issue to verify the fix without paying for a full re-crawl') and steers toward a selector over a URL list. It stops short of naming the alternative tool (e.g., enqueue_crawl) or explicit when-not-to-use conditions, so it's strong 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?

With no annotations, the description carries the full burden, and it does disclose two useful traits: result ranking and the tenant-membership auth requirement. It omits whether this is purely read-only, pagination/cursor behavior, and any rate limits, leaving meaningful 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?

Three tight sentences with zero filler; the core capability and result behavior are front-loaded, followed by the access constraint.

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

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

For a search tool with no output schema, the description covers what is searched, the result count behavior, and the access requirement. It stops short of describing result shape (ranked documents vs alerts) or whether results are cross-type merged, but is broadly 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 description coverage is 100%, so the schema already documents all four parameters (including query semantics and the limit cap). The description only restates 'limit' and the tenant constraint, adding nothing beyond structured fields. 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 ('Search') and resource set ('sites, pages, and alerts') scoped to a tenant. This is enough for an agent to know it is the general discovery tool, though it never names or contrasts any 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?

Provides one prerequisite ('caller must be a member of the given tenant') but no when-to-use vs when-not guidance or alternatives (e.g. versus the crawl-specific getters). Usage is only implied by the tool's obviously generic 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?

With no annotations, the description carries the full burden and does disclose a non-obvious cascading side effect: it deletes every ignore rule (page, site-wide, route-pattern) and explains why. It still omits auth requirements, reversibility of those deletions, and error behavior when no rules exist.

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

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

Two tight sentences, front-loaded with the action and followed by the critical side effect and its rationale. No filler and nothing redundant with 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?

For a single-parameter mutation with no annotations and no output schema, the description covers the action and the important destructive consequence. It leaves a minor gap around response behavior and what happens when there are no ignore rules to delete.

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 alertId parameter, so the schema already documents the input. The description adds no format, sourcing, or validity detail beyond that, which is the baseline-3 case for a one-parameter tool.

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

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

"Reopen an ignored alert" states a specific verb and resource, and the concept of undoing an ignore makes it implicitly distinguishable from the sibling ignore_alert. However, it never names the sibling it inverts, so an agent must infer the pairing from semantics rather than being routed 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?

The usage is implied by the verb (reopen something previously ignored), and the note about deleting ignore rules gives a strong hint about when this is the right call. But there is no explicit when-to-use vs. when-not statement and no named alternative such as ignore_alert.

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