Technical SEO audit tools over MCP. Wrendex crawls a site with 140+ checks (broken links, redirects, canonicals, hreflang, sitemaps, structured data, duplicate trackers, render-blocking resources, Core Web Vitals page weight) and exposes crawl runs, issues and fix lists as tools so coding agents like Claude Code, Cursor and Codex can audit and fix a site. Stateless Streamable HTTP; authenticate with a Wrendex bearer token from https://wrendex.com/docs.
Scored across 17 tools
Most tools target clearly distinct resources (tenants, sites, crawls, billing). The one dense cluster is get_crawl_alerts vs get_crawl_issues vs get_crawl_issue_summary, which all concern crawl findings; the descriptions work hard to disambiguate them (per-page alerts vs grouped-by-type summary vs deduped-by-reach rollup), so an agent can usually choose correctly but may still hesitate.
Nearly all names follow a consistent snake_case verb_noun pattern (list_sites, get_crawl, enqueue_crawl, ignore_alert, unignore_alert). The lone deviation is the bare verb 'search', which breaks the pattern slightly but remains readable.
17 tools for a multi-tenant crawl/SEO platform with billing is on the heavier side but each tool maps to a real operation (crawl lifecycle, alert handling, billing, search). It sits just above the ideal 3-15 range without obvious redundancy.
Core lifecycle is well covered: enqueue/cancel/get/list/recrawl crawls, alert inspection and ignore/unignore, issue summaries, health history, search, and checkout. The notable gap is site management - get_site and list_sites exist but there is no create/update/delete site, which could dead-end an agent setting up a new workspace.
Stop an in-flight crawl run. Pages already crawled are kept and scored; the run finishes in status "cancelled". Returns 409 if the run has already finished crawling. Requires a WRITE-scoped token and EDITOR, ADMIN or OWNER role.
| Name | Required | Description | Default |
|---|---|---|---|
| crawlId | Yes | Path parameter crawlId. |
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.
Create a Stripe Checkout link that subscribes the workspace to a plan. Returns {url, sessionId}. Nothing is charged until a person opens the url and completes payment, so hand it to whoever owns the workspace. A workspace a person signed up for has zero credits and cannot crawl until a plan or credit pack is on the account; one created through POST /api/agent/signup starts with a one-time free grant and can crawl until it runs out. The caller must be an OWNER or ADMIN of the tenant. An agent-created workspace must be claimed by a person first: until then this returns 409 WORKSPACE_UNCLAIMED with the claimUrl to send them. Plan prices and monthly credits: GET /api/pricing (no token needed).
| Name | Required | Description | Default |
|---|---|---|---|
| tenantId | Yes | Path parameter tenantId. | |
| priceTier | Yes | Plan to subscribe to. base is the cheapest; studio and agency carry more monthly credits and storage. | |
| returnUrl | No | Where Stripe sends the person after checkout. Must be a page on the dashboard origin; defaults to the workspace's billing page. Leave it out unless you have a reason. |
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 thoroughly: no charge occurs until a human opens the URL, the return shape is {url, sessionId}, caller must be OWNER or ADMIN, and an unclaimed agent workspace yields 409 WORKSPACE_UNCLAIMED with a claimUrl. It also explains the credit-state consequences of subscribing, which is rich behavioral context beyond any structured field.
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 and return value are front-loaded, then constraints and failure mode. It is long, and the credit-grant/crawl-eligibility sentences border on tangential, but each sentence supplies a fact an agent needs to avoid a wrong call.
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 by naming the return fields, the no-charge semantics, the authorization requirement, and the specific error/claim flow. Nothing an agent needs in order to invoke or interpret the result 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 domain meaning the schema lacks: it explains what subscribing actually grants (monthly credits, ability to crawl) and why one would need it, indirectly clarifying priceTier selection. tenantId gets no added semantics, keeping it short of 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 ("Create a Stripe Checkout link") plus the effect ("subscribes the workspace to a plan"), and names the return payload. No sibling tool touches billing, so this is unambiguously distinguishable from the crawl/alert/site 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 clear context for use: hand the URL to whoever owns the workspace, and points to GET /api/pricing for plan prices. It also states the prerequisite authority (OWNER or ADMIN). It stops short of explicit when-not-to-use/counterpart routing, but there is no sibling alternative to route to for billing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enqueue a new recursive crawl run for a site. Returns the queued CrawlRun, or the already-active run if one is queued or running. Requires a WRITE-scoped token and EDITOR, ADMIN or OWNER role, and consumes crawl credits.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Path parameter siteId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses idempotent-like return behavior ('or the already-active run if one is queued or running'), auth requirements, and credit consumption. It does not cover rate limits or error behavior, but the core behavioral traits are well 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?
Three sentences, front-loaded with the core action, then return behavior, then requirements. No wasted words; every sentence adds distinct value.
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 no annotations, no output schema, and minimal parameter documentation, the description does a good job covering purpose, return value, auth, and credit cost. It could add a note on idempotency or error cases, but it is largely complete for a one-param mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter siteId has a schema description ('Path parameter siteId.'), so schema coverage is 100%. The description adds only the phrase 'for a site', which barely enriches meaning. Per baseline for high coverage, a 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?
Description states a specific verb and resource: 'Enqueue a new recursive crawl run for a site.' It also clarifies the return behavior. However, it does not explicitly distinguish this tool from siblings like recrawl_pages or cancel_crawl, so an agent must infer the full-site recursive scope from context.
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 prerequisites (WRITE-scoped token, EDITOR/ADMIN/OWNER role, crawl credits) but does not state when to prefer this tool over alternatives such as recrawl_pages or list_crawls. Usage context is implied by 'new recursive crawl run' but no explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single crawl run by id, including its status and progress.
| Name | Required | Description | Default |
|---|---|---|---|
| crawlId | Yes | Path parameter crawlId. |
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.
List individual alerts for a crawl run, each with its pageUrl, message, detail, and affectedUrls. Checks that report per target (broken links, images, stylesheets, scripts, mixed content) file one alert per target, so affectedUrls holds that single URL and the HTTP status is in the message; for HTTP_404 the pageUrl itself is the failing URL. Pass type to drill into one issue type (e.g. LINKS_TO_BROKEN, HTTP_404, DUPLICATE_H1). Pass a filter or pagination param so the response is the filtered, paginated result.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-based page index (default 0). | |
| size | No | Page size (default 50, capped). | |
| type | No | Alert type to filter by, e.g. LINKS_TO_BROKEN, HTTP_404, DUPLICATE_H1. | |
| status | No | Filter by status: OPEN, RESOLVED, IGNORED. | |
| crawlId | Yes | Path parameter crawlId. | |
| severity | No | Filter by severity: ERROR, WARNING, NOTICE. Accepts a comma-separated list, e.g. 'ERROR,WARNING'. | |
| pageUrlContains | No | Only alerts whose page URL contains this substring. |
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.
Summarize the SEO and quality issues found in a crawl run, grouped by type and severity (ignored alerts excluded).
| Name | Required | Description | Default |
|---|---|---|---|
| crawlId | Yes | Path parameter crawlId. |
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.
Roll a crawl's alerts up into unique issues to fix, ranked by reach. The checks emit one alert PER PAGE, so a single dead external URL linked from 400 pages looks like 400 findings in get_crawl_alerts; here it is ONE item with target=the dead URL and pageCount=400. Prefer this over get_crawl_alerts when answering 'what should I fix first' or 'which broken links does this site have'. Items are grouped by (type, affected URL); checks about the page's own text group by that text instead, so TITLE_TOO_LONG yields one item per offending title with target=the title and targetIsSubject=true. Checks naming neither (e.g. TITLE_MISSING) yield one item per type with target=null. Narrow with category (e.g. 'External Links') or type. Ignored alerts are excluded unless includeIgnored=true. Each item's pageUrls list is capped - trust pageCount for reach and use get_crawl_alerts for the full page list.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-based page index (default 0). | |
| size | No | Groups per page (default 50, capped). | |
| type | No | Alert type to filter by, e.g. EXTERNAL_LINK_4XX, LINKS_TO_BROKEN. Takes precedence over category. | |
| crawlId | Yes | Path parameter crawlId. | |
| category | No | Catalog category to filter by, e.g. 'External Links', 'Title', 'Images'. Use get_crawl_issues to list them. | |
| severity | No | Filter by severity: ERROR, WARNING, NOTICE. Accepts a comma-separated list, e.g. 'ERROR,WARNING'. | |
| includeIgnored | No | Include ignored alerts (default false). | |
| pageUrlContains | No | Only alerts whose page URL contains this substring. |
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.
Page through the duplicated code regions of one DUPLICATE_JS_CODE or DUPLICATE_CSS_CODE alert, each with the two source locations, the measured shared bytes, and the code snippet. Use this to read the actual duplicated code: the crawl-wide duplicate-code report carries no snippets at all, because it returns every finding in the crawl at once.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-based page index (default 0). | |
| size | No | Regions per page (default 10, max 50). | |
| alertId | Yes | Path parameter alertId. |
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.
Get a site's health-score history (one point per crawl).
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Path parameter siteId. |
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.
Get a single site's configuration and metadata within a tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Path parameter siteId. | |
| tenantId | Yes | Path parameter tenantId. |
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.
Ignore an alert with a required scope. ALWAYS ask the user which scope they want before calling: current_page (only this URL), all_pages (this issue type across the whole site), route_pattern (pages matching a glob like /blog/*), or target_pattern (every URL the issue is ABOUT that matches a glob - broken links, images - wherever they are linked from). Creates a persistent ignore rule so future crawls keep the issue suppressed.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | Ignore scope. Ask the user; do not guess. | |
| alertId | Yes | Path parameter alertId. | |
| routePattern | No | Glob over the PAGE the issue was found on, matched against its path or its whole URL, where * matches anything: /blog/* or https://docs.example.com/*. REQUIRED when scope=route_pattern, forbidden otherwise. | |
| targetPattern | No | Glob over the whole URL the alert is ABOUT, host included, where * matches anything: */auth/*, *example.com/* or https://example.com/assets/*. REQUIRED when scope=target_pattern, forbidden otherwise. Only alerts that name a URL can be ignored this way. |
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.
List crawl runs for a site, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Path parameter siteId. |
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.
List all sites belonging to a tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| tenantId | Yes | Path parameter tenantId. |
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.
List the workspaces (tenants) your token can access, with their ids. Call this FIRST - the returned tenant id is the tenantId argument the other tools (list_sites, search, ...) need. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Re-crawl only the pages affected by one finding in a site's most recent completed crawl, then re-run that crawl's analysis and update its health score in place. Use after fixing an issue to verify the fix without paying for a full re-crawl. Name the finding with a selector rather than a URL list where possible: a summary row can cover far more pages than it lists. Requires a WRITE-scoped token and ADMIN or OWNER role, and consumes one crawl credit per page.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Page, resource or redirect-source URL. For selector=urls, a whitespace or comma separated list. | |
| lang | No | Duplicate-code language. For selector=duplicate-code-group. | |
| type | No | AlertType name, e.g. BROKEN_INTERNAL_LINK. For selector=issue-group. | |
| field | No | Which duplicated field. For selector=duplicate-cluster. | |
| target | No | Group target: the affected URL for issue-group, or the shared value (or body hash) for duplicate-cluster. | |
| alertId | No | Alert id. Required for selector=alert. | |
| crawlId | Yes | Path parameter crawlId. | |
| blockKey | No | Duplicate-code block key. For selector=duplicate-code-group. | |
| selector | Yes | Which kind of finding to re-crawl. alert: one alert by id. duplicate-code-group: a duplicate-code block by lang+blockKey. issue-group: an issue summary row by type+target. redirect: a redirecting page plus what links to it. resource: the pages referencing a resource URL. duplicate-cluster: pages sharing a title/description/h1/body. page: one page URL. urls: an explicit list. |
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.
Search a tenant's sites, pages, and alerts. Returns up to limit ranked results. The caller must be a member of the given tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Free-text search query. | |
| limit | No | Max results to return (default 20, hard cap 50). | |
| tenantId | Yes | Tenant id (24-char hex) to search within. | |
| activeSiteId | No | Optional site id to bias ranking toward the current site. |
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.
Reopen an ignored alert. Also deletes every ignore rule covering it (page, site-wide, or route-pattern) so the next crawl does not silently re-ignore the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | Path parameter alertId. |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
cancel_crawlcreate_checkout_sessionenqueue_crawlget_crawlget_crawl_alertsget_crawl_issue_summaryget_crawl_issuesget_duplicate_code_regionsget_health_scoreget_siteignore_alertlist_crawlslist_siteslist_tenantsrecrawl_pagessearchunignore_alert
Add one secure layer between your agents and this server.