SiteDoctor

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation, so the safety bar is partly covered. The description adds the meaningful extras of owner-only auth and a manual verification precondition, but says nothing about idempotency, whether negative or zero credits are accepted, audit logging via tx_note, or what happens on failure.

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 that leads with the authorization scope and ends with the precondition. Nothing is redundant or 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 credit-granting mutation with no output schema, zero documented parameters, and two easily confused key parameters, the description leaves too much unspecified. An agent cannot tell which key receives credits, what tx_note is for, or what the result looks like.

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 0%, so the description must carry all parameter meaning and it carries none. The distinction between api_key (caller's key) and target_key (customer's key) is exactly what an agent could get wrong, and tx_note is never mentioned.

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 ('Add credits to a customer key') plus a precondition, which is far more informative than the title alone. It only implicitly distinguishes itself from the read-only sibling check_credits, so sibling differentiation is not explicit.

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 both an authorization constraint ('Owner only') and a triggering condition ('after verifying their crypto payment'), which is enough for an agent to know when this applies. It stops short of naming the alternative tool or stating what to do when the payment is unverified or the key is invalid.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without prose. The description contributes the one thing annotations cannot express: that the operation is restricted to the owner, an authorization constraint an agent must check before invoking. It says nothing about scope of the aggregates, caching, or cost, so it adds some but not rich behavioral 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 eight-word sentence with the access restriction front-loaded in parentheses, so the reader hits the gating condition first. Nothing is wasted, though the brevity is partly under-specification rather than discipline.

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 saying what the stats actually contain, and "platform usage stats" does not do so — an agent cannot tell whether it will receive counters, time series, or per-endpoint breakdowns. Combined with an undocumented api_key, a read-only tool this simple still leaves the caller guessing on both input and return.

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 required parameter api_key has 0% schema description coverage, so the schema provides a name and type only. The description does not compensate at all — it never mentions the key, its format, where to obtain it, or whether it must belong to the owner account, which is exactly the ambiguity the "(Owner only)" note creates.

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?

"Show platform usage stats" gives a verb and a resource, so the agent knows this is a read of aggregate platform metrics rather than a per-entity lookup. However, "usage stats" is left undefined (credits? scans? API calls?), and no sibling is named or excluded, so differentiation from check_credits or check_broken_links is only inferable from the word "platform".

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?

"(Owner only)" is a permission precondition, not usage guidance; it does tell the agent who may call it, which is useful. But there is no statement of when to prefer this tool over check_credits or the other siblings, and no mention of what to do when the caller is not the owner.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the credit cost (2 credits), the fact that crawling is remote/open-world, and that the sample of links tested is capped, which materially affects what results the agent will see.

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, no filler, with the operation and cost front-loaded ahead of the constraint detail. Every clause carries information an agent needs before calling.

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 states the return shape (broken links plus HTTP status) and the sampling limit, which is enough to set expectations. It is slightly thin on crawl scope (single page vs. site-wide) and on the api_key parameter, but nothing blocking for a simple 3-parameter read-only tool.

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

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

Schema description coverage is 0%, so the description must carry the load. It does well on max_links, giving the default (25) and hard ceiling (50), and 'crawl a page' implies the url parameter's meaning. The api_key parameter receives no explanation, though it is conventional, so the compensation is partial rather than complete.

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

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

The description uses a specific verb ('Crawl a page and test its links') and names the concrete output ('every broken link with HTTP status'), so the agent knows exactly what the tool produces. It does not explicitly differentiate itself from the sibling scan_website, which is the only reason it falls short of a 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 implied rather than stated: the tool is clearly for link validation, and the credit cost hints at when it is worth invoking. However, there is no explicit when-to-use guidance and no mention of when to prefer scan_website or check_page_seo instead, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that this is a per-API-key balance lookup, but says nothing about what happens on an invalid or exhausted key, rate limits, or error behavior.

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 with the resource and scope front-loaded and no wasted clauses. It is efficient, though the terseness contributes to the missing usage detail.

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 read-only tool with no output schema, the description covers the essential identity of the operation. It still leaves the shape of the result (a numeric balance, a structured object, remaining scans vs. dollars) unspecified, which is the main completeness 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 0% for the single api_key parameter, so the description must compensate. It partially does by identifying the value as a SiteDoctor API key (a credential rather than an account identifier), but adds no format, sourcing, or error semantics for that key.

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 ('Check remaining credits') scoped to a 'SiteDoctor API key', which distinguishes it from add_credits and register_free_key without naming them explicitly. Clear enough that an agent would not confuse this with a scan or SEO check 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 or when-not-to-use guidance, and no mention of alternatives such as add_credits for topping up. The only contextual hint is that it operates on an API key, leaving routing decisions to inference from the tool name.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint), and the description adds genuinely new behavior: the 1-credit cost and the explicit scope boundary that link crawling is excluded. It does not disclose authentication expectations around api_key or what happens when credits run out, which matters for a paid endpoint.

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 tight sentence plus a short scope disclaimer; the cost and the check inventory are front-loaded, and no wording is padding.

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 enumeration of inspected items effectively communicates the shape of the result even without an output schema, and credit cost is disclosed. However, with no output schema and zero parameter documentation, the undefined api_key/auth handling is a real hole for a tool an agent must call correctly on the first try.

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 0%, so the description carries the full burden. 'url' is self-evident, but 'api_key' with an empty-string default is never mentioned — an agent gets no signal on whether it must supply a key or whether the default implies optional/pre-authenticated calls.

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 ('on-page SEO check') and enumerates exactly what is inspected: title, meta description, headings, alt coverage, canonical, Open Graph, robots.txt, sitemap.xml. The closing 'Skips link crawling' separates it from check_broken_links and scan_website 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?

The 'Fast on-page SEO check (1 credit)' framing plus 'Skips link crawling' tells an agent this is the cheap single-page audit rather than a crawl, which implicitly routes link checking elsewhere. It stops short of naming the sibling to use for crawling or full-site scans, so the alternative is inferred rather than stated.

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

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

Annotations only declare it is non-read-only, non-destructive and closed-world; the description adds the important context that no email or payment is required, that a key with 25 credits is issued, and that the key must be retained for later calls. It does not cover idempotency or whether calling twice creates multiple keys, leaving a small gap.

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

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

Two short sentences, front-loaded with the core action and its benefit, followed by the one post-call instruction that matters. No redundant or filler wording.

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

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

For a parameterless tool with no output schema, the description supplies everything needed: what it creates, what it costs (nothing), and what to do with the returned key. There is no hidden complexity left unexplained.

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

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

The tool takes zero parameters, so there is nothing the description needs to disambiguate; baseline for a parameterless tool is 4. The description correctly avoids inventing inputs.

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

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

States a specific verb and resource: 'Register a free SiteDoctor API key', plus concrete terms (25 credits, no email or payment). This is clearly distinguishable from siblings like add_credits and check_credits, which manage credits rather than create a key.

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 what to do with the result: 'Store the returned key and pass it as api_key to the scanning tools', which effectively routes usage toward scan_website/check_page_seo. It does not state whether repeated calls are safe or when not to call it, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the credit cost (3 credits) and the shape of the result (score, letter grade, per-category breakdown, issues, top fixes). It does not mention latency, async behavior, or failure modes, so it stops short of a 5.

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

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

Two tightly packed sentences: the first front-loads the operation, scope, and cost; the second covers return values. No filler, no redundancy with the annotation title.

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

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

With no output schema, the description correctly compensates by describing the return payload (0-100 score, letter grade, categories, issue list, top fixes), which is the most important context an agent needs. The remaining gap is input-side: URL format and api_key expectations are unaddressed for a tool with 0% schema coverage.

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

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

There are two parameters at 0% schema description coverage, and the description says nothing about either. It never clarifies the expected URL format (scheme, trailing path) or what api_key is for or whether it is optional, leaving the agent to guess on both required-input semantics and authentication.

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 (full website health audit) on a specific resource (a website URL) and enumerates exactly what is checked: SEO, performance, security headers, SSL, mobile readiness, content, broken links. The enumerated scope plus the return-value list makes it distinguishable from narrower siblings like check_page_seo and check_broken_links without opening 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?

The '(3 credits)' tag gives an implicit cost tradeoff against the cheaper single-purpose siblings, and 'Full ... audit' implies this is the broad option. However, there is no explicit statement of when to choose this over check_page_seo or check_broken_links, and no prerequisites or exclusions are given.

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