SEO audit of every page: what to fix first, a fix prompt for your framework, and a re-check.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 17 tools
Each tool targets a distinct object and action: sites, findings, fixes, verification, links, search data, focus pages, and settings. Overlaps such as findings_list vs fix_first and mark_fixed vs ignore_finding are clearly differentiated by scope and side effects in the descriptions. An agent should be able to select the right tool without confusion.
All names use snake_case consistently, avoiding casing chaos. However, the verb/noun ordering is mixed: most are verb_noun (add_site, set_brief), while several are noun-first (findings_list, sites_list, link_suggestions). This is still readable but not a fully predictable pattern.
17 tools is slightly above the ideal 3–15 range, but the domain is broad and each tool appears to cover a distinct part of the SEO audit/fix lifecycle. The set is not bloated with redundant operations, though it could be tighter.
The surface covers adding and listing sites, scanning, finding and prioritizing issues, ignoring/marking fixes, verifying changes, link suggestions, search performance, and focus/brief settings. Minor gaps exist, such as deleting or updating a site, reopening ignored findings, or exporting reports, but core workflows are covered.
Add a website to the account and start its first scan, the same as adding it in the dashboard. Takes a domain or any URL on the site, and optionally a path that limits the project to one region or section (e.g. /us). The scan finds the site's pages and checks them, usually in 5 to 20 minutes. Adding a site already in the account returns that site (alreadyAdded: true). The plan decides how many sites an account can have, and the pages the scan checks in depth use the plan's monthly pages (audit:run scope).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Project name. Defaults to the domain. | |
| path | No | Optional region or section to scan instead of the whole site, e.g. /us. | |
| domain | Yes | example.com, or any URL on the site. | |
| language | No | Language of the site's fix instructions, reports and emails. Defaults to en. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key behavior: the scan runs asynchronously with a 5–20 minute duration, duplicate adds return alreadyAdded: true, and plan limits govern site count and scan depth. No statement contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The paragraph is five sentences, but each sentence adds distinct information: action, input form, scan duration, idempotency, and plan constraints. It is slightly dense but not 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?
With no output schema, the description covers the response behavior for duplicates and gives enough context about timing and plan constraints to invoke the tool correctly. It falls short of describing the full return payload, but that is not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description largely restates the parameter descriptions for domain and path rather than adding new parameter-level meaning. It adds plan context (audit:run scope) but does not materially expand on what each parameter means 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 opens with a specific verb and resource: 'Add a website to the account and start its first scan.' It also clearly distinguishes this from sibling rescan_site by emphasizing this is the first scan of a newly added site.
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 clearly frames the tool as the dashboard-equivalent action for adding a site and explains what happens for duplicates, so an agent understands the main use case. However, it does not explicitly name alternatives such as rescan_site or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record what happened to a link suggestion: accepted once the link is in the source, dismissed if it is not worth adding. Changes Loomaly's work item only.
| Name | Required | Description | Default |
|---|---|---|---|
| decision | Yes | ||
| suggestionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a meaningful side-effect note: "Changes Loomaly's work item only," which is not fully captured by the annotations. Since annotations already include idempotentHint=true and destructiveHint=false, this extra scoping is valuable and not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the primary purpose, explains the decision values, and closes with a side-effect note, making every sentence earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with useful annotations, the description covers purpose, decision semantics, and side-effect scope. It does not mention return behavior or the relationship to link_suggestions, but neither is essential for this 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?
With schema description coverage at 0%, the description must carry parameter meaning. It explains the `decision` enum values well in context, but it provides no additional semantics for `suggestionId` beyond its name in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Record what happened to a link suggestion," and immediately clarifies the two possible decisions. It clearly conveys what the tool does, though it does not explicitly contrast itself with sibling tools like link_suggestions or log_change.
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 provides conditions for each decision value: use `accepted` once the link is in the source, use `dismissed` if it is not worth adding. However, it gives no explicit guidance about when to use this tool versus related siblings such as link_suggestions or log_change.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List findings for a site, newest first. Each one carries the rule that produced it, the affected URL and the evidence. Filters: ruleId, pathTemplate, url, severity, state.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Only this page (a full URL). | |
| limit | No | 1-100, default 25. | |
| state | No | Defaults to open. `resolved` = marked fixed, waiting for a re-check. | |
| ruleId | No | Only this rule's findings. | |
| siteId | Yes | From sites_list. | |
| severity | No | Filter by severity. Omit for all. | |
| pathTemplate | No | Only pages of this template, e.g. /blog/*. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that results are newest first and that each finding carries rule, URL, and evidence. It doesn't disclose pagination behavior beyond the limit parameter, or what happens when state is omitted (defaults to open, which is in the schema). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The core action and result content are front-loaded, followed by a compact filter list. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 100% schema coverage and no output schema, the description is nearly complete. It covers what the tool returns (findings with rule, URL, evidence) and ordering. It doesn't describe the output format, but with no output schema and a simple list tool, that's a minor gap. The annotations cover safety, so nothing critical 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 schema already documents all 7 parameters. The description adds a compact filter list and clarifies that state defaults to open (though the schema also says this). It doesn't add meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('findings for a site'), with ordering ('newest first') and content details (rule, URL, evidence). It clearly distinguishes from siblings like mark_fixed or ignore_finding, which are mutations, and from sites_list, which lists sites.
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 usage context: list findings for a site, with filters. It doesn't explicitly say when to use this vs alternatives, but the filter list and 'newest first' ordering give clear context. It doesn't mention exclusions like 'use verify to re-check' but the sibling names make the distinction fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The site's open issues in the order Loomaly recommends fixing them (the dashboard's queue). By default one entry per rule — usually one change in a shared layout or template — with the page templates it touches, how many pages, a sample page and one of its findings (sampleFindingId), when a scan last saw it, the points fixing it adds to the health score (scoreGain, 0 when it adds none), and why it ranks where it does. lastScanAt and scanAgeDays say when the site's last whole-site scan finished; the queue reflects the site as of then. by: "template" gives one entry per rule × template. ruleId with pathTemplate identifies one group.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | Defaults to rule. | |
| limit | No | 1-100, default 10. | |
| state | No | Defaults to open. `resolved` lists claimed fixes awaiting a re-check. | |
| siteId | Yes | From sites_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does: it discloses the deduplication rule, the scoreGain edge case (0 when adding none), and the important staleness caveat that the queue reflects the site only as of the last completed whole-site scan. It stops short of covering pagination behavior or response envelope structure.
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 identity of the tool and its ordering logic are front-loaded in the first clause, followed by the entry payload and the grouping mode. Density is high but every clause carries a distinct fact; the only mild drag is the long inline enumeration of returned fields in a single unbroken sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry the return shape — and it does, naming the per-entry fields, the sample finding reference, and the scan timestamps. Combined with 100% parameter coverage it is nearly self-sufficient; the only gap is explicit routing relative to sibling list/read tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining semantics the schema only states tersely: what a 'template' grouping entry means (rule × template), that one rule entry usually maps to a single shared-layout change, and that ruleId + pathTemplate jointly identify a group.
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?
It names a specific resource and scope: the site's open issues ordered by Loomaly's recommended fix priority, explicitly framed as 'the dashboard's queue'. This distinguishes it from the raw sibling findings_list by conveying prioritization and rule-level deduplication. An agent can tell what it gets back 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?
Usage is implied rather than stated: it explains defaults (state=open, one entry per rule) and the alternate grouping mode, but never says when to reach for this over findings_list, focus_page, or fix_prompt. No exclusions or prerequisites are given, so the agent must infer routing from the priority framing alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return everything needed to fix one finding in the repository: the rule, the affected URL, the evidence, and a framework-aware instruction written for a coding assistant (devPrompt, in the site's language). When the same rule is open on other pages of the URL's template, template gives the template and how many of its pages have it. guidance is the official documentation the rule rests on, effort a rough size of the fix (minutes, hours or days), and convention is true when the rule is common practice rather than a search engine requirement.
| Name | Required | Description | Default |
|---|---|---|---|
| findingId | Yes | From findings_list, or fix_first's sampleFindingId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent and non-destructive behavior, so the bar is lower. The description adds substantial context beyond them by explaining what the response contains, including that devPrompt is written for a coding assistant in the site's language and that template reports open instances across a template's pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the core purpose, then defines each returned field in compact clauses. It is dense and long-ish, but each clause maps to a distinct returned field and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the full burden of explaining return values, and it does so field by field (devPrompt, template, guidance, effort, convention). Combined with annotations covering the safety profile, an agent has what it needs to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage, and the schema already says the findingId comes from findings_list or fix_first's sampleFindingId. The description adds no further parameter semantics, 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?
The description states a specific verb and resource: 'Return everything needed to fix one finding in the repository,' and enumerates the returned payload (rule, URL, evidence, devPrompt, template, guidance, effort, convention). This distinguishes it from findings_list (which enumerates findings) and fix_first, though it does not name those siblings directly in the description text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose (fetch fix instructions for one finding), and the schema points to findings_list and fix_first as sources of findingId. However, the description itself gives no explicit when-to-use, prerequisites, or alternatives, so the agent must infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The one page the owner is working on this week, and everything needed to judge it: the owner's brief (what the site sells, to whom, what counts as a conversion), the page's Search Console numbers for the last 28 days against the 28 before, its open issues, a conversion checkup (the page read against the brief: offer, audience, outcome, proof, a step towards the conversion, the last doubts — fail items are usually the best next change), and the change log with a verdict on each change (the 14 days before it went live against the 14 after; watching until that data is in). Each checkup item carries the question it answers. When no focus page is set, returns candidates: pages already seen in search but not near the top (Search Console needed). noise means the change had no measurable effect; miss means the page climbed but did not convert better, since conversions decide over rankings.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it returns candidates when no focus page is set, explains the meaning of 'noise' and 'miss' verdicts, and notes the Search Console dependency for candidates. This goes beyond annotations and helps the agent understand the tool's output and external requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-organized, front-loading the main purpose and then enumerating the components. Every sentence adds value, though it is somewhat long. It is appropriately structured for the complexity of the return data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description thoroughly explains what the tool returns: the owner's brief, Search Console comparisons, issues, conversion checkup with 'fail' items, change log with verdicts, and fallback to candidates when no focus page is set. It also defines key terms like 'noise' and 'miss'. This is sufficient for an agent to understand the tool's output and behavior without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required parameter siteId with no description, and the tool description does not mention it at all. With 0% schema coverage, the description fails to add any meaning for the parameter, leaving the agent to infer that siteId is likely a site identifier but without explicit confirmation.
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 clearly states the tool's purpose: to return the focus page and everything needed to judge it, including the owner's brief, Search Console numbers, issues, conversion checkup, and change log. It distinguishes itself from siblings like set_focus_page by focusing on retrieval and even describes the fallback behavior when no focus page is set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool's name and content, but the description does not explicitly state when to use this tool vs alternatives like set_focus_page. No exclusions or when-not-to-use guidance is provided, so an agent must infer that this is the read-only getter for focus page data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark one finding (findingId), a group (ruleId + pathTemplate, or ruleId + sampleUrl) or a whole rule (ruleId + allPages: true) as ignored, with the reason. Ignored findings leave the fix-first queue and the health score, and stay ignored when a later scan finds them again; a person can reopen them in the dashboard. Changes Loomaly's work item only, never the website (findings:write scope).
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | Why it is not a problem, in a sentence; shown to the site's team. | |
| ruleId | No | ||
| siteId | Yes | ||
| allPages | No | With ruleId: every page this rule is open on. | |
| findingId | No | ||
| sampleUrl | No | ||
| pathTemplate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds substantial behavioral detail: ignored findings persist across future scans, can be reopened by a person, and changes only Loomaly's work item, never the website. This meaningfully expands what the agent can infer about side effects and reversibility.
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 cover action, parameter combinations, consequences, persistence, reversibility, and permission scope with no filler. The opening sentence front-loads the core operation and invocation patterns, making the definition highly efficient to parse.
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 description is complete for a mutation tool with no output schema: it specifies all invocation shapes, required intent, persistence behavior, reversibility, and permission scope. An agent has enough information to call the tool correctly and understand its side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 29% schema description coverage, the description carries most of the parameter meaning. It explains how findingId, ruleId, pathTemplate, sampleUrl, and allPages combine into three valid invocation modes, which is beyond what the schema provides. It does not explicitly explain siteId or reason, but their roles are reasonably inferable from context.
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 starts with a specific verb ('Mark') and clearly names the resource being acted on: a single finding, a group, or a whole rule, with the exact parameter combinations for each. This makes the tool's purpose unambiguous and distinguishes it from related actions like fixing or rescanning.
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 makes clear this is for issues that are 'not a problem' and explains the consequences (leaving the fix-first queue and health score). It provides solid context but does not explicitly name alternative tools or say when not to use it, stopping short of a fully explicit routing guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal links worth adding: on page fromUrl, turn anchor inside sentence into a link to toUrl. Each is a single edit in the source page. They are suggestions for a person to approve; roughly one in five is not worth adding.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1-100, default 25. | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by clarifying the output is a set of suggestions for human approval and noting that roughly one in five is not worth adding, giving the agent realistic quality expectations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core purpose front-loaded, followed by concise details about the edit type, approval requirement, and quality. Every sentence earns its place with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only suggestion-list tool with two parameters, the description covers the nature and structure of the suggestions, including a quality caveat. It doesn't specify the exact return format (list vs. single object) or how results connect to sibling tools, and no output schema exists to fill that gap, but the essentials for calling it correctly are present.
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 description does not explain the two parameters, siteId and limit. The schema documents only limit (50% coverage), leaving siteId undefined in both schema and description. The description instead focuses on response fields (fromUrl, anchor, sentence, toUrl), so an agent gets no added semantic guidance for constructing a correct call.
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 clearly states the tool's function: it returns internal link suggestions, each described by fromUrl, anchor, sentence, and toUrl. It explicitly says these are suggestions for a person to approve, not actual edits, which distinguishes it from sibling tools like decide_link or mark_fixed that act on links.
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 is for retrieving candidate internal links before a human approves them, but it never explicitly states when to use it versus alternatives like decide_link or findings_list. No exclusion criteria or alternative tool names are given, leaving usage context only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a change that went live on a page — what changed, the day it went live (YYYY-MM-DD, default today) and the commit or PR — so Loomaly can compare the 14 days before with the 14 after; the comparison is anchored on the go-live day, so it records deployed changes, not drafts. Optionally pass the conversions the owner counted before and after. Changes Loomaly's log only, never the website.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Commit or PR URL. | |
| page | No | The page: a full URL, a path such as /pricing, or a page id. Defaults to the focus page. | |
| siteId | Yes | ||
| summary | Yes | What changed, in a sentence. | |
| shippedOn | No | YYYY-MM-DD (UTC). | |
| conversionsAfter | No | ||
| conversionsBefore | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=false and destructiveHint=false, and the description adds the key side-effect statement: 'Changes Loomaly's log only, never the website.' It also explains the go-live anchoring and the default date, going beyond the annotations without contradicting them.
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 with no filler, and the core action plus constraints are front-loaded. It earns its length by adding context (14-day comparison, log-only side effect) rather than repeating schema content.
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 write tool with no output schema, the description covers the when and why but omits the return value/acknowledgment and doesn't mention siteId's role. It's functional for calling the tool, but the missing output behavior and the unexplained required parameter leave gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 57% (about 4 of 7 properties described). The description adds value for shippedOn (default today), ref (commit or PR), and conversions (owner-counted before/after), but it never explains siteId, which is required, and adds little beyond the schema for page. With moderate coverage, this is adequate but not high.
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?
Clearly states the action ('Record'), the resource (a change that went live on a page), and the key data captured. The note 'records deployed changes, not drafts' distinguishes it from hypothetical draft-logging and no sibling tool overlaps with this action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use (a change that went live, anchored on go-live day) and what not to record ('not drafts'). It stops short of naming alternative tools, but the sibling set contains no competing logging tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Marks one finding (findingId), a group (ruleId + pathTemplate, or ruleId + sampleUrl) or a whole rule (ruleId + allPages: true) as fixed. It needs only the change (a commit or an open PR), not a deployed page. It moves to 'pending verification': the next re-audit closes it if the issue is gone and sends it back to open if it isn't; a person can also verify it in the dashboard. ref holds the commit or PR URL shown to the reviewer. This changes Loomaly's work item only, never the website.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Commit or PR URL. | |
| note | No | What changed, in a sentence. | |
| ruleId | No | ||
| siteId | Yes | ||
| allPages | No | With ruleId: the fix covers every page this rule is open on (a layout-level change). | |
| findingId | No | ||
| sampleUrl | No | ||
| pathTemplate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only state idempotent/not-destructive/not-read-only), the description discloses the resulting state ('pending verification'), what happens on re-audit (closes if gone, reopens if not), that a human can verify in the dashboard, that ref is surfaced to a reviewer, and the crucial scoping fact that this changes Loomaly's work item and never the website.
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 action and its scope options, then the lifecycle, then the boundary of the side effect. No filler and no repetition of schema fields.
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 output schema, the description adequately covers the post-call state and the non-destructive boundary, and annotations cover safety. It omits error/validation behavior (e.g., what happens with an invalid combination of targeting parameters), which is a minor remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 38% schema coverage, the description carries most of the parameter burden: it defines the three valid targeting combinations covering findingId, ruleId, pathTemplate, sampleUrl, and allPages, and explains that ref holds the commit/PR URL shown to the reviewer. It adds little on siteId or note, but compensates well for most of the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('marks ... as fixed') and resource ('a finding / group / whole rule'), and it enumerates the exact parameter combinations that select each scope (findingId, ruleId+pathTemplate, ruleId+sampleUrl, ruleId+allPages). An agent can distinguish this mutation from siblings like verify, ignore_finding, and verify_status 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 usage context: only the change (commit or open PR) is needed, not a deployed page, and it explains the pending-verification lifecycle. It does not, however, name alternative tools (e.g., ignore_finding or the dashboard verify path) with explicit when-to-use conditions, so routing between siblings is still partly inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new scan of the whole site: find its pages again and check them, the same as the dashboard's scan button. Findings that are gone close; new ones open. Refused while a scan is already running, and until 24 hours after the last scan started on the free plan (1 hour on a paid plan). The pages it checks in depth use the plan's monthly pages (audit:run scope).
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | From sites_list. |
The site's Google search numbers from its connected Search Console: clicks, impressions, click-through rate and average position for the latest 28 days of data against the 28 days before (range, previousRange; Search Console runs two to three days behind), the pages with the most clicks (topPages, with each page's clicks in the previous window), and strikingDistance: queries a page ranks 11 to 20 on average for, with at least 10 impressions, most impressions first. connected: false when Search Console isn't connected for the site; needsReconnect when Google stopped accepting the connection. Both come with connectUrl, the dashboard page to (re)connect it.
| Name | Required | Description | Default |
|---|---|---|---|
| pages | No | How many top pages. Default 10. | |
| siteId | Yes | ||
| queries | No | How many striking-distance queries. Default 15. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive, but the description adds genuinely useful behavior: Search Console data 'runs two to three days behind,' and the failure states 'connected: false' / 'needsReconnect' plus the 'connectUrl' to reconnect. That auth/connection context is real value beyond the annotations. It omits any error handling or rate/pagination limits, keeping it at 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense paragraph, front-loaded with the primary metrics before drilling into topPages and strikingDistance. Nearly every clause carries information an agent needs, especially given there is no output schema. It is on the long side and the parenthetical `range`/`previousRange` aside interrupts flow, so not a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining returns, and it does so thoroughly: metric set, 28-day-vs-prior-28-day comparison, topPages, strikingDistance thresholds, and disconnection states. It is nearly complete, only leaving the siteId parameter and the ambiguous range/previousRange references unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, above the midpoint, and the schema already documents pages (default 10) and queries (default 15). The description links these to outputs ('topPages', 'strikingDistance' queries ranking 11-20 with >=10 impressions), adding meaning, but siteId is undocumented in both schema and description, and the referenced `range`/`previousRange` do not appear in the input schema, which is mildly confusing.
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 concretely names the resource and scope: 'The site's Google search numbers from its connected Search Console: clicks, impressions, click-through rate and average position.' That is far more specific than the name alone and separates it from sibling tools like findings_list or link_suggestions, which are about fixes/links rather than analytics. It stops short of a crisp verb-led statement or an explicit sibling comparison, so a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent infers it should call this when it needs Search Console metrics. There is no explicit 'use this when…' statement, no when-not guidance, and no named alternative (e.g. versus focus_page or sites_list). The surrounding detail describes content, not selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the owner's brief: what the site sells (offer), to whom (customer) and what counts as a conversion (conversion), up to 300 characters each. The focus page's conversion checkup is read against it and needs offer and conversion. Empty strings for all three clear it. Changes Loomaly's settings only, never the website (findings:write scope).
| Name | Required | Description | Default |
|---|---|---|---|
| offer | Yes | ||
| siteId | Yes | ||
| customer | Yes | ||
| conversion | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write, idempotent, non-destructive operation, but the description adds critical context: it affects only Loomaly settings, has a 300-character limit per field, clearing behavior with empty strings, and a dependency on the focus page's checkup. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the main purpose, then adding constraints and scope. Every sentence adds value with no redundancy, achieving high information density in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, the description covers the action, parameter semantics, side effects, dependencies, and scope. An agent has all necessary information to invoke it correctly, including the clearing edge case and the relationship to the focus page checkup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description carries full responsibility for parameter meaning. It explicitly defines offer (what the site sells), customer (to whom), conversion (what counts as a conversion), and implies siteId as the target site. It also specifies length constraints, making all parameters fully understandable.
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 clearly states the tool's purpose: 'Save the owner's brief' and enumerates the specific fields (offer, customer, conversion) with their meanings. It distinguishes itself from siblings like set_focus_page by targeting the brief specifically, and clarifies it changes settings only, not the website.
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 explains when to use the tool: to set the brief that the focus page's conversion checkup reads, noting that offer and conversion are required. It also specifies the clearing behavior with empty strings and explicitly states it never touches the website, guiding an agent away from using it for website edits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose the one page the owner works on this week (a full URL, a path such as /pricing, or a page id), or clear it with page: null. The page must be one Loomaly has found on the site. Changes Loomaly's settings only, never the website (findings:write scope).
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Full URL, path or page id; null clears the focus page. | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it explicitly states the change affects only Loomaly's settings, never the website, and mentions the page must be one Loomaly has found. It does not contradict annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It lacks details on error handling or rate limits, but these are not critical for a simple setter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it states the core action first, then the clearing option, then the prerequisite and scope. No wasted words, and it front-loads the primary use case.
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 setter with no output schema, the description is largely complete. It covers purpose, page format, clearing, and scope. It omits an explanation of siteId and does not address potential error scenarios (e.g., invalid page), but these are minor given the tool's simplicity and the presence of idempotentHint in annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (page has a description, siteId does not). The description adds little beyond the schema: it repeats the page format and null-clearing behavior but does not explain siteId at all. It also adds the 'page must be found' constraint, but that's not a parameter format. With low coverage, the description should compensate for the missing siteId documentation, which it fails to do.
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 clearly states the tool's purpose: setting the focus page for the week, with explicit mention of clearing via null. It distinguishes itself from the sibling 'focus_page' (which likely retrieves the current page) by indicating this is the setter. The scope ('Changes Loomaly's settings only') further clarifies its role.
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 provides clear context on when to use this tool (to set or clear the focus page) and even specifies the page format (URL, path, or ID). It also notes a prerequisite (page must be found by Loomaly). However, it does not explicitly name alternative tools or state when not to use it, though the 'focus_page' sibling implies a getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the sites this account can see: id, project name, the address scanned (url, including a region path such as /us when the project covers one region), open issue counts, when the project was added, when a whole-site scan last finished (lastScanAt; one-page re-checks don't move it), and where its scan stands (scan.phase: finding_pages, checking_pages, done, not_started or failed, with pages found so far). While a first scan is running, the site has no findings yet. verified says whether the owner has proved the site is theirs; an unverified site is scanned only when asked (no weekly re-scan or weekly report), and verifyUrl is the dashboard page that verifies it. When the account has no site, the result also has addSiteUrl, the dashboard page that adds one, with {domain} to be replaced by the site's domain.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds extensive behavior: lastScanAt semantics (one-page re-checks don't move it), scan.phase enum values and meaning, first-scan findings state, unverified-site scanning policy, verifyUrl, and addSiteUrl on empty account. This is substantial disclosure beyond structured fields.
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 purpose, then packs return-field semantics into a dense paragraph. Given no output schema, most sentences earn their place, but it could be better structured with bullets. Appropriate length for the information density.
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, so the description must carry return values. It details fields, scan phases, verification consequences, and empty-account response, making the tool callable and interpretable without extra docs. Minor omission: no pagination or ordering info, but list semantics are otherwise covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero input parameters and an empty schema. The rule baseline for 0 params is 4, and no parameter descriptions are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List the sites this account can see') and immediately scopes it to the account's visible sites. It makes the tool's role clear against add_site/verify/rescan_site siblings, though it does not explicitly name an alternative tool.
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 when-to-use guidance, no when-not, and no alternatives are mentioned. The description is entirely about output fields and behavior, leaving the agent to infer that this is the discovery tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-crawl the page of one finding (findingId), or of up to limit pages of a group (siteId + ruleId with pathTemplate, sampleUrl or allPages: true), and recompute the findings to decide whether the issue is gone. Asynchronous: returns one auditRunId per page, each with its findingId. A page re-checked in the last 10 minutes returns that run instead of reading the page again; every other page uses one of the plan's monthly pages. An account can re-check 20 pages a day on the free plan and 200 on a paid plan (UTC days); at most 5 scans or re-checks start a minute (audit:run scope). It reads the live page, not the working tree, so it reflects a fix only once the fix is deployed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Pages to re-check for a group: 1-25, default 5. | |
| ruleId | No | ||
| siteId | No | Needed for a group. | |
| allPages | No | With ruleId: every page this rule is open on. | |
| findingId | No | ||
| sampleUrl | No | ||
| pathTemplate | No |
Report whether re-checks have finished and what happened to each finding: fixed, still-open, inconclusive (the re-check could not measure it, e.g. the speed test returned nothing, so the finding still waits for a re-check), check-failed or pending. Takes one auditRunId with its findingId, or runs as verify returned them for a group.
| Name | Required | Description | Default |
|---|---|---|---|
| runs | No | Up to 25. | |
| findingId | No | ||
| auditRunId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, so the safety profile is settled. The description adds real value by enumerating the finding outcomes (`fixed`, `still-open`, `inconclusive`, `check-failed`, `pending`) and explaining what `inconclusive` means, which is behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the reporting behavior and followed by the calling convention. The long parenthetical defining `inconclusive` is informative but slightly heavy for its position; overall it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully carries the return semantics via the status enumeration and the `inconclusive` explanation. It also covers the two input modes. Minor gaps remain around whether single IDs and `runs` are mutually exclusive and polling expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only `runs` has a description, 'Up to 25.'). The description partially compensates by explaining the two call shapes — a single auditRunId/findingId pair or a `runs` array as verify returned it — which the schema does not express. However, it does not document the format or semantics of the individual findingId/auditRunId values.
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: reporting whether re-checks have finished and the fate of each finding. It references the sibling `verify` ('as verify returned them'), giving some differentiation from the tool that starts verification, but it never explicitly contrasts the two roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied — you call this after `verify` to poll completion status — but there is no explicit when-to-use statement, no when-not-to-use, and no named alternative among the many siblings. The agent must infer the workflow from 'as verify returned them'.
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.
search_performanceadd_sitefindings_list3 fields changedInput schema / properties / pathTemplateAdded value: +{
+ "description": "Only pages of this template, e.g. /blog/*.",
+ "type": "string"
+}Input schema / properties / ruleIdAdded value: +{
+ "description": "Only this rule's findings.",
+ "type": "string"
+}Input schema / properties / urlAdded value: +{
+ "description": "Only this page (a full URL).",
+ "type": "string"
+}fix_prompt1 field changedInput schema / properties / findingId / descriptionPrevious value: -"From findings_list."New value: +"From findings_list, or fix_first's sampleFindingId."ignore_findingrescan_siteset_briefset_focus_pageverify7 fields changedInput schema / properties / allPagesAdded value: +{
+ "description": "With ruleId: every page this rule is open on.",
+ "type": "boolean"
+}Input schema / properties / limitAdded value: +{
+ "description": "Pages to re-check for a group: 1-25, default 5.",
+ "type": "number"
+}Input schema / properties / pathTemplateAdded value: +{
+ "type": "string"
+}Input schema / properties / ruleIdAdded value: +{
+ "type": "string"
+}Input schema / properties / sampleUrlAdded value: +{
+ "type": "string"
+}Input schema / properties / siteIdAdded value: +{
+ "description": "Needed for a group.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "findingId"
-]verify_status2 fields changedInput schema / properties / runsAdded value: +{
+ "description": "Up to 25.",
+ "items": {
+ "properties": {
+ "auditRunId": {
+ "type": "string"
+ },
+ "findingId": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "auditRunId",
+ "findingId"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Input schema / requiredRemoved value: -[
- "auditRunId",
- "findingId"
-]decide_linkfindings_listfix_firstfix_promptfocus_pagelink_suggestionslog_changemark_fixedsites_listverifyverify_statusAudit a page for Google and AI search (ChatGPT, Claude, Perplexity); get a fix pack to apply.
Audit a website for technical and on-page SEO problems.
One-call audit: robots.txt AI-bot rules, llms.txt, JSON-LD, meta tags, sitemap. Score plus fixes.
Audit a page for search and AI answer engines; generate robots.txt, sitemap, head, llms.txt.
Add one secure layer between your agents and this server.