ROAS Expert free AI SEO audit

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), yet the description adds genuinely new behavioral facts: the 10-25 second runtime, the daily-per-client rate limit, and the important gating detail that failure/warning specifics and platform fixes are locked until a work email is used via unlock_report. That locked-vs-unlocked split is exactly the kind of context an agent cannot infer from annotations or schema.

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 first sentence front-loads the action and the full return payload, and the remaining sentences each carry distinct, non-redundant information (unlock path, latency, input constraint, rate limit). It is somewhat run-on with several clauses packed into the opening sentence, which keeps it just short of ideal.

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 describe returns, and it does so thoroughly (score, grade, platform, category scores, top three issues, all 48 check statuses, shareable link). Combined with the latency note, the rate limit, the email-gated unlock path, and the URL constraint, an agent has everything needed to call it and set 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 100% and the single 'url' parameter is already documented, so the structured data carries the load (baseline 3). The description still adds constraint meaning beyond the schema by specifying that a deep link is invalid and only a domain or homepage URL is acceptable.

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

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

Names a specific verb and resource ('Runs the free ROAS Expert audit on a public website') and enumerates the concrete output surface: score out of 100, grade, detected platform, category scores, top three issues, status of all 48 checks, and a report link. It also points at the sibling boundary by stating that per-check detail and fixes are 'unlocked ... through unlock_report', so an agent can distinguish it from unlock_report/explain_fix/get_report 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 clear invocation context ('Use the domain or homepage URL, not a deep link') and a stated operational limit ('Free plan: a few audits per day per client'), plus it routes the user to unlock_report for deeper detail. It does not explicitly state when to prefer get_report, list_checks, or explain_fix instead, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety and repeatability are covered. The description adds one genuinely useful behavioral fact beyond them — 'No usage limit' — which matters for agents deciding to call it repeatedly, but it says nothing about return format, error behavior, or unknown platform handling.

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 dense sentences with no filler; the core action and its scope lead, and the platform list plus the no-limit note follow. Every clause earns its place.

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

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

For a two-parameter read tool with no output schema, the description covers what is returned ('fix text'), the keying (one check id), the platform dimension, and rate-limit behavior. Only minor gaps remain around failure modes and output 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 coverage is 100% so the baseline is 3, but the description goes further by enumerating the accepted platform values (shopify, wordpress, magento, framer, webflow, wix, squarespace, bigcommerce, hubspot, nextjs, generic), which the schema leaves as an unenumerated 'platform key or CMS name'. That enumeration is real added value.

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 (returns), resource (fix text for one check id), and scope (per-platform). It is clearly differentiated from siblings such as list_checks (which enumerates checks) and get_report (which returns the report), so an agent can pick this 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?

Explicitly tells the agent where the check_id comes from — 'from list_checks or a report' — which routes it from sibling tools. It lacks an explicit when-not condition (e.g. what to do if the check id is unknown or the platform is unsupported), but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds genuinely non-obvious behavior: retention of 90 days, no usage limit, and the content difference between locked (top three issues + check statuses) and unlocked (all findings, fixes, written summary) reports. It doesn't cover failure modes for an invalid or expired id.

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: identity and id source first, then what is returned, then retention and limits. No filler and nothing important buried at the end.

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

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

With no output schema, the description carries the return-value burden and does so explicitly (issues, check statuses, findings, fixes, summary). Retention and rate-limit context round out what an agent needs to call and interpret this tool correctly.

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

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

Schema coverage is 100% and the schema already states the id is 8 characters, so the baseline is 3. The description adds real value by explaining that the id is the trailing segment of a tools.roasexpert.com/r/<id> link, which tells the agent how to source the value.

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 ("Returns a previously run audit by its id") and immediately clarifies where the id comes from via the URL format. It is clearly distinguishable from siblings like audit_site (runs a new audit) and unlock_report (changes report state).

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 locked vs. unlocked distinction gives the agent a clear sense of what this tool yields in each case and implicitly routes to unlock_report when full findings are needed. It lacks an explicit "use this when / not when" statement or direct naming of the alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely non-structured context: 'No usage limit,' which tells the agent there is no quota barrier to calling it repeatedly, plus the grouping/weighting behavior of the result.

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

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

Three short sentences with zero padding: purpose, use case, and a constraint. The purpose is front-loaded and every sentence 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?

There is no output schema, and the description usefully compensates by describing what the return contains (checks, categories, weights, one-line pass descriptions). It omits result size/pagination details, but for a small read-only catalogue this is a minor gap.

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

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

Schema description coverage is 100% and the single parameter is an enum-backed optional category filter already fully documented in the schema. The description's phrase 'grouped by category' loosely echoes the parameter but adds no new syntax or filtering semantics, so baseline 3 applies.

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

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

The description names a specific resource ('the catalogue of checks the audit runs') and specifies the shape of the output (grouped by category, with weights and a one-line pass description). This makes it clearly distinct from audit_site (which runs the audit) and get_report (which returns results), so an agent can route 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 states two concrete use cases ('explain a score' and 'see what the audit covers'), which gives the agent a clear context for invocation. It does not, however, explicitly name a sibling alternative or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true, but the description goes well beyond them by disclosing the actual side effect: the email is sent to a third-party CRM along with the report link, and the user receives at most one follow-up. It also clarifies the no-usage-limit behavior, which is real operational context an agent needs before invoking a non-read-only 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 sentences, front-loaded with the payoff of unlocking, followed by side effects and then the usage constraint. Every clause carries information the agent cannot get from the schema or annotations; nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so by describing exactly what is returned (failing and warning checks, per-platform fixes, written summary). Combined with the disclosed email side effect and consent constraint, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; however the description adds genuine meaning for the email parameter by explaining where it is transmitted and that it must be user-provided for this purpose, and it implies the id links back to audit_site output. It does not add format or validation detail for id 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 and resource ("Unlocks a report") and immediately enumerates what the unlock yields: failing/warning checks with detail, platform-specific fixes, and the written summary. This clearly separates it from get_report, list_checks, and explain_fix without needing their schemas.

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

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

Gives an explicit precondition ("Only call this with an email the user gave you for this purpose") and notes there is no usage limit, which tells the agent it need not ration calls. It stops short of naming an alternative sibling (e.g. get_report for the un-unlocked version), so the routing guidance is contextual rather than complete.

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