Scopeweb

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

Annotations already convey read-only, idempotent, open-world, and non-destructive behavior, and the description reinforces these with 'Read-only' and 'Cannot spend money.' The added behavioral detail about performing a live fetch of observable surface signals goes beyond the annotations and gives the agent useful safety and cost expectations.

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 compact and front-loaded: it opens with usage guidance, then lists the fetched fields, then states safety/cost constraints. Each sentence serves a purpose, though the two 'Use...' sentence stems could have been merged without loss of clarity.

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

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

For a one-parameter read-only tool with no output schema, the description is well-rounded: it covers input semantics, operation scope, the exact observable signals returned, and safety/spend constraints. Minor gaps like error handling for non-resolving domains and input normalization are acceptable given the simple, safe nature of the operation.

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 schema contains only a required 'domain' string with no descriptions, so the description must compensate. It adds meaningful semantic context by clarifying the domain is the user's existing/owned site, not a new candidate name. However, it does not specify the expected input format (e.g., bare domain vs protocol, trailing slash, punycode), leaving some ambiguity for invocation.

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/resource: 'Fetch a live domain's observable surface' and lists concrete outputs (HTTP status, redirect target, title, meta description, h1 headings, tech hints). It also distinguishes the domain from siblings by noting this is for names the user already holds, not for finding new ones.

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 explicitly tells the agent when to use the tool: when the user asks what is wrong with a site they own, wants an existing name assessed, wants to compare deployment against a spec, or wants to know if a domain serves anything. It signals when not to use it by saying 'rather than a new one found,' though it does not name specific sibling tools as alternatives.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: 10-domain cap, RDAP-backed real-time authority, 404 also returned for reserved/premium names, and that it returns 'registered' rather than 'active'/'dormant' because it does not fetch the site. It even warns the result is registration-only and says nothing about quality. Strong, though return-format detail partially duplicates the output 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 critical rule is front-loaded in the first line and the ordering constraint follows immediately, which is good structure. However it is long and repeats the 'final gate before recommending a purchase' idea twice and restates the registration-only scope in two separate sentences, which could be trimmed.

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 check with an output schema, the description covers everything an agent needs: ordering relative to siblings, the 10-domain limit, what the result does and does not mean, and how edge cases (reserved/premium, unvetted names) behave.

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 0% for the single domains parameter, so the description must compensate. It adds a real constraint the schema lacks ('up to 10 domains') but never clarifies the expected string format (bare name vs. FQDN, whether a TLD is required), leaving the one parameter partially specified.

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+method: 'Real-time authoritative registration check for up to 10 domains via RDAP', and explicitly distinguishes it from siblings by naming suggest_names and score_name as the prior steps. The 'answers only is this registered' framing nails the exact scope.

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?

Explicit when-to-use ('immediately before you recommend buying anything', 'any time an earlier answer said unknown/pending/unprobed'), when-not-to-use ('THE LAST GATE, NOT THE FIRST STEP', not before suggest_names/score_name), and what to do instead if names were not vetted. Routing is fully specified.

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?

Adds substantial behavioral context beyond the annotations: drafts persist across conversations, every version is content-screened, and flagged drafts still return a draft_id but serve a 451 preview. No contradiction with idempotentHint or destructiveHint exists.

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 compact and front-loaded with the key usage condition. Every sentence adds a distinct fact: storage location, return values, persistence, and screening behavior.

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 tool with no output schema, it names the persistent draft_id and live preview_url return values, explains the flagged-content behavior, and provides lifecycle routing to list_drafts. Combined with sibling names, an agent has the needed context 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 description coverage is 100%, including the note that index.html is required for a browsable preview, so the description does not need to add much param-level detail. The description's 'for a name' aligns loosely with name_hint but adds no new semantics.

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 action (creating a draft site/page/landing) and resource (user's Scopeweb portfolio). It distinguishes from sibling update_draft through the 'nothing to edit yet' condition and from list_drafts via the 'future sessions to resume work' pointer.

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 states when to use: when the user wants a draft and there is nothing to edit yet. It also names list_drafts for future resumption, but could go further by explicitly saying 'use update_draft to edit an existing draft.'

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

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

No annotations are provided, so the description carries the burden, and it does disclose the categories of returned data (registration status, claim vs renewal price, provenance). It implies a read operation but never states that explicitly, and gives no information about permissions, rate limits, or behavior on unknown/unregistered domains.

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 front-loaded sentences that state scope first and the input convention second; no filler. Slightly dense capitalization ('AND') but structurally efficient and appropriately sized for a one-parameter tool.

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?

An output schema exists, so return values need no prose explanation, and the single parameter is fully documented. The description covers what data is retrieved and the input format. The main remaining gap is the absence of any disambiguation from adjacent tools, which the usage dimension already penalizes.

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 defines id as 'A domain name.', so the baseline is 3. The description adds meaning beyond that by giving a concrete example ('atlas.io'), clarifying the expected format is a bare domain with no scheme or path.

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 scope: it returns registration status, claim price, renewal price, and provenance for a single domain. 'Everything we hold about one domain' is a clear aggregate-fetch purpose. It does not, however, explicitly contrast itself with overlapping siblings such as quote_domain, check_live, or audit_domain, so the agent must infer the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The only 'how' instruction is the format of the id, which is parameter-level, not usage routing. With siblings like quote_domain and check_live that could plausibly overlap, an agent gets no help choosing.

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, and the description reinforces this with 'Read-only. Cannot spend money.' It adds behavioral context beyond annotations by stating that it returns metadata and file list, or file content, which is not covered by 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?

Three sentences, each serving a purpose: first explains the primary use case, second describes the functional behavior, third adds safety and context. It is slightly wordy but front-loads the key usage guidance and remains efficient overall.

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 read-only tool with only two parameters and no output schema, the description provides enough information: what the tool does, when to use it, and what it returns. It doesn't detail response format, but for a get operation without an output schema, this is acceptable.

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 50%, and the description compensates by explaining that 'path' returns file content and that without it, the tool returns metadata and file list. The draft_id parameter is self-evident but not explicitly described; the description adds value for the optional parameter.

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 verb 'Get' and the resource 'draft', and specifies exactly what is retrieved (metadata, file list, or file content). It distinguishes itself from siblings like update_draft and list_drafts by emphasizing read-only retrieval and the specific use case of resuming work on a draft.

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 explicitly says 'Use this before editing a draft you did not create in this conversation' and 'Use to resume work on a draft from a previous conversation,' giving clear when-to-use guidance. It does not explicitly name alternatives or exclusions, but the context is sufficient to infer that it's for reading drafts, not creating or modifying them.

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, idempotentHint=true, and destructiveHint=false, so the read-only nature is clear. The description adds valuable context about the `partial` flag indicating headroom is an upper bound, and explains the meaning of `reason: foreign_registrar_pricing` for unknown costs. It also clarifies that transfer prices are not renewal prices. This goes beyond the annotations, though it does not describe the exact output structure (no output schema), but that is partially covered by describing the 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?

The description is moderately long but every sentence serves a purpose, covering usage context, output specifics, and caveats. It is front-loaded with 'Use this before recommending anything with a price', which immediately tells the agent when to invoke. No filler or repetition.

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 tool's complexity (multiple financial concepts, partial data, unknown costs), the description covers the essential caveats: headroom upper bound when partial, unknown cost reasoning, and transfer price distinction. The single parameter is clear, and the output schema is absent, so the description's field listing helps the agent understand what to expect. It is complete enough to avoid misinterpretation.

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 has only one parameter, `project_id`, with no description. The parameter is self-explanatory, so the description adds minimal value by not detailing what project_id references if ambiguous. However, since there is only one required parameter and it is standard, the agent can infer meaning. The description itself does not elaborate on the parameter, but the schema coverage is 0%, so the description does not need to compensate for missing param descriptions; the baseline is 3 because the single param is trivially named.

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 retrieve the fiduciary readout for a project, including budget, costs, headroom, and unknown counts. It specifies the verb 'get' and the resource 'finance', and the context 'Use this before recommending anything with a price' distinguishes it from siblings like `quote_domain` or `get_draft`.

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 explicitly instructs when to use the tool: before recommending anything with a price. It also tells the agent to read `carry_unknown_count` before quoting headroom, and warns against treating transfer prices as renewal prices. It implicitly differentiates from `quote_domain` by focusing on account-level finances rather than per-domain quotes.

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 readOnly/idempotent/destructive, but the description adds substantially more: 'Cannot spend money,' the shape of returned data (source, URL, what it may be cited FOR), and the critical epistemic caveat that a vector search 'always returns its nearest neighbour, so it always looks confident; nearness is not correctness.' That is real behavioral context 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-loaded with the core directive and well organized, but it repeats itself almost verbatim — 'Use this to understand how something works' and 'Do NOT use it to decide anything' each appear twice, and the retrieval-not-authority warning is stated in two places. The redundancy costs size without adding 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?

With an output schema present, return values need not be explained, and the annotations plus description together cover safety, authority precedence, and use context well. The one gap is parameter behavior (top_k, query format), which nothing else supplies.

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 2 parameters (query, top_k), and the description never explains query syntax or the meaning/effect of top_k. Since the schema does not compensate, the description should have covered this and does not.

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 precise verb and resource plus scope: 'Semantic search over a small curated corpus: this system's own documentation and methodology, ICANN policy, and per-registry policy documents.' An agent can immediately distinguish this retrieval tool from siblings like check_live, get_finance, or search.

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?

Explicit when-to-use ('understand how something works before explaining it'), when-not-to-use ('Do NOT use it to decide anything'), and names the alternatives that win: 'registry policy comes from GET /tld/:tld/policy... registration status comes from check_live via RDAP/WHOIS.' The precedence rule is spelled out rather than implied.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description earns credit for adding beyond them: 'Cannot spend money' clarifies cost safety, and the scan_age_ms note warns that a stale verdict must not be read as fresh — a genuinely useful operational caveat not present in 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 the trigger condition and the inventory contents, which is the right order. Slightly redundant tail ('Use before suggesting the user buy anything' overlaps with the opening 'what do I own' framing, and the cost note repeats the read-only idea), but nothing is wasted enough to hurt.

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?

A zero-param read tool with an output schema and full annotation coverage needs only trigger guidance, scope, and any behavioral caveat — all present, including the freshness warning about scan_age_ms. Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description does not attempt to invent or misdescribe inputs, which is correct behavior here.

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 precise verb and resource ('List the user's domain inventory') and immediately scopes the content: every domain with a verification challenge issued or completed, plus cached liveness, classification, title and expiry. An agent can distinguish it from siblings like audit_domain or verify_ownership without opening 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?

Explicitly states when to invoke ('at the start of any portfolio, renewal or what do I own question') and an exclusion-style rule ('before assuming which names the user holds', 'before suggesting the user buy anything'). This routes the agent ahead of quote_domain/suggest_names rather than leaving ordering to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' is largely a restatement. 'Cannot spend money' is a genuine addition beyond annotations and is meaningful given siblings like set_budget and quote_domain, but the description adds little else about behavior or scope of results.

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, front-loaded with the core action and ending on the usage cue. Minor redundancy: 'Read-only' duplicates the readOnlyHint annotation, so one clause does not fully 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?

An output schema exists, so return values need not be spelled out, and the description correctly avoids that burden. For a zero-parameter read tool with rich annotations, purpose, safety, and usage are all covered; only sibling differentiation 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?

The tool takes zero parameters, so the baseline is 4. The description enumerates the returned fields, which helps set expectations even though it adds nothing parameter-related (there is nothing to add).

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

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

States a specific verb and resource ('List all drafts in the user's Scopeweb portfolio') plus the returned fields (status, preview URLs, timestamps). The 'all drafts' scope implicitly separates it from get_draft, but no sibling is named explicitly, so it stops short of the top band.

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?

'Call this at the start of a session to see existing work' gives a clear triggering condition. It does not mention when to prefer get_draft or how to narrow results (no filtering params exist), so no explicit alternatives are offered.

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?

Goes well beyond the annotations: it discloses that the authoritative registration gate is re-run before quoting, that undetermined or registered names are never quoted, that premium names are quoted at real price or refused, that expired quotes are re-quoted rather than honoured, and that project_id can never alter the number. This is exactly the extra behavioural context annotations cannot carry.

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 front-loaded trigger and the return-field list are efficient, but the middle is a wall of text that restates the no-purchase guarantee four or five times ('NOT a purchase', 'cannot make one', 'cannot spend money', 'no tool to complete an order', 'no verb that spends'). Content volume is justified; the repetition is not.

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?

Output schema exists, yet the description still names the key return fields, and it covers the edge cases an agent would otherwise have to guess at (registered names, indeterminate status, premium pricing, quote expiry, budget invariance). Nothing needed to call this correctly and interpret the result 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 both parameters are already documented, including that project_id never changes the price. The description restates the budget-context semantics at length but adds no new syntax, format, or constraint information, so the baseline of 3 applies.

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

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

States a specific verb (quote a price) and resource (a domain name), and explicitly bounds the operation: 'Reads prices only' and 'Returns total_cents, renewal_cents, an expiry, and a confirm_url.' An agent can distinguish this from sibling mutation tools like create_draft or set_budget purely from the 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?

'Use this when the user has chosen a name and wants the real price' gives a clear trigger condition, and the text explicitly excludes the purchase flow ('It is NOT a purchase and you cannot make one'). However, it never routes the agent among the other read-oriented siblings (audit_domain, check_live, score_name, list_domains), so the selection guidance is contextual rather than comparative.

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, openWorldHint, idempotentHint, and destructiveHint, covering safety and mutation. The description adds valuable context beyond annotations: it states it cannot spend money (a cost constraint) and lists the specific return fields (registered, resolves, serves, parked, classification, liveness). This enriches the behavioral picture without contradicting any annotation.

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 exactly two sentences: the first front-loads the core action and constraint, the second provides the alternative tool and the return summary. Every word earns its place, with no fluff or repetition.

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 a single parameter, no output schema, and moderate complexity, the description is fully sufficient. It explains what the tool does, its constraints, its alternative, and the shape of its return data. An agent has everything needed to invoke it correctly without further elaboration.

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

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

Schema description coverage is 100% for the single 'candidates' parameter, which already explains it expects full domain names with a max of 25. The tool description adds the notion of an 'explicit list', implying exact matches rather than fuzzy or conceptual input. This is a subtle nuance beyond the schema but not substantial—the schema already carries the core meaning, so a baseline score of 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 explicitly states the verb 'Classify' and the resource 'an explicit list of candidate domains' with a clear maximum of 25. It also distinguishes itself from suggest_names, which is a sibling tool, making the purpose unambiguous and easy to differentiate.

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 explicitly says to use suggest_names instead when you have a concept rather than a list, giving clear when-to-use and when-not-to-use guidance. It also notes that the tool is read-only and cannot spend money, which further clarifies appropriate usage.

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, idempotent, non-destructive, openWorld=false), yet the description still adds material behavioral context: no spending, score/weight/basis per component for auditability, severe properties CAP the total rather than averaging, and unmeasurable components returned as unavailable rather than estimated. This is substantive disclosure that annotations cannot express.

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 usage and the sibling exclusion before moving to behavioral caveats, and each sentence carries distinct information. It runs long and some sentences are dense, but none are filler or repetition of the name.

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

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

An output schema exists, so return structure need not be explained, and the description instead supplies the scoring model, the capping rule, and the explicit non-claims. For a read-only scoring tool with this complexity, nothing an agent needs in order to call or interpret it is missing.

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

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

Schema description coverage is 100%, so both 'domain' and 'domains' (single vs. up to 10, ranked best-first) are already fully documented in the schema. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('grade candidate names on measurable properties of the string') and enumerates the actual dimensions scored. It explicitly distinguishes itself from the nearest sibling by name ('Not for deciding availability, which is check_live'), so an agent can separate them without opening 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 trigger ('when the user is choosing between names, or asks whether a name is any good'), an explicit exclusion routing to the alternative ('check_live'), and two further scope exclusions (not a search-ranking prediction, not a trademark search). Nothing about when to select this tool is left to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the result categorization (sellable, restricted, not ours to sell, taken, not checked), which tells the agent the output is a set of names with defensibility states. It says nothing about cost, rate limits, whether search registers or reserves anything, or how the states are determined; those gaps keep this at a minimum-viable 3 for an unannotated 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 short sentences, front-loaded with the purpose and followed by the return semantics and the input rule. Nothing is padded, though 'each with the state we can defend' is slightly loose phrasing for what is really a status enumeration.

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?

An output schema exists, so return values need not be spelled out, yet the description helpfully summarizes the possible states. For a single-parameter read-style lookup, the purpose, input rule, and result shape are all covered; only operational details (cost, limits, any side effects) are absent.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds a constraint the schema does not state: the input must be a concept rather than a domain string. That negative guidance materially reduces the risk of calling the tool with the wrong value type, pushing it slightly above baseline.

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 concrete verb and resource: find domain names for an idea, returning candidates across every ending with a defensibility state. That is far more specific than the bare name 'search', and the line 'Pass the concept, not a domain' implicitly separates it from domain-taking siblings like audit_domain or check_live. It does not, however, explicitly distinguish itself from suggest_names or scan_namespace, which are plausible confusions.

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?

'Pass the concept, not a domain' gives a genuine input-selection cue that steers the agent away from the domain-checking siblings. There is no explicit when-to-use/when-not statement, no named alternative, and no prerequisites (auth, cost, whether it registers anything) are mentioned.

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?

The description goes well beyond the annotations by explaining response behavior (CURRENT CARRY and HEADROOM are precomputed), edge-case semantics (unknown renewal prices count as unknown, never zero, making headroom an upper bound), and the important fact that budget affects recommendations but never prices. This is rich, non-obvious behavioral detail.

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 front-loaded with the usage trigger and contains valuable details, but several sentences repeat the same point: 'It records their ceiling', 'Records a number you chose', and 'Cannot spend money and cannot buy anything' are redundant. The all-caps pricing sentence also adds noise despite being important.

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?

Despite having no output schema, the description explains what the response contains (CURRENT CARRY and HEADROOM) and the special partial-headroom case. It also addresses pricing misconceptions. Missing only minor details like overwrite behavior, but with idempotentHint=true and the rich narrative, this is adequate 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 description coverage is 0%, so the description must carry the weight. It does this by explaining that period is monthly or yearly, amount is expressed in cents, and the target is a project. It does not give detailed constraints or ranges, but it meaningfully maps to all three parameters.

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 specific verbs and resources: it records a spending limit for a project and never authorizes a purchase. It clearly differentiates itself from purchase-related actions and from pricing tools by stating it cannot spend or buy anything and that prices are unaffected by budget.

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 an explicit trigger: 'Use this when the user states a spending limit for a project.' It also provides exclusions ('never authorises a purchase', 'Cannot spend money and cannot buy anything'), but does not name alternative sibling tools or explicitly contrast with them.

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 readOnly, idempotent and non-destructive, and the description goes further by stating it cannot spend money, cannot start/change/cancel a subscription, and that the response lists exactly what does not vary by tier. It stops short of describing return shape or pagination, but adds real behavioral value.

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-loaded with the trigger condition and the read-only guarantee, but the closing paragraph about plans gating depth rather than truth is long and repeats the read-only point. It earns its place as a guard against misleading the user, yet could be tightened.

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?

An output schema exists, so return values need not be explained; the description covers when to call it, safety constraints, and the tier/truth distinction an agent must not misrepresent. Complete for a zero-parameter read tool.

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

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

The tool takes zero parameters, so the schema-description baseline of 4 applies. The description correctly implies no input is needed to produce the account-specific plan view.

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 (show available plans) and enumerates the payload: each plan's contents, the caller's current tier, and used allowance. It is clearly separable from sibling billing tools like get_finance and set_budget.

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 two explicit triggering conditions — the user asking what a tier costs or hitting a limit, and a refusal that names this tool as the recovery path. It also states what the tool is not for, ruling out subscription mutation.

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?

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive) the description discloses the money constraint ('cannot spend money'), the scan_id deep-walk convergence over ~3 calls, the unregistered-vs-purchasable distinction, and the critical pricing invariants ('prices are identical for all buyers', budget affects ordering not cost). These are non-obvious behavioral traits an agent would otherwise get wrong.

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

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

Front-loaded with the '★ START HERE' directive and workflow, then caveats. The rename-history sentence is long but earns its place by explaining the discoverability fix. Dense overall, with minor redundancy across the pricing/budget sentences.

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?

An output schema exists, so return values need no explanation, and the description still covers everything else an agent needs: the entry-point role, the follow-on tool chain, pagination via scan_id, and the purchase/pricing caveats that gate downstream actions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by characterizing 'query' as a CONCEPT (word or short phrase) and explaining that re-querying the same scan_id walks deeper and converges, which the schema only weakly signals with 'Resume a previous browse'.

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 candidate names across a namespace') and immediately positions itself as the entry point for naming tasks. It explicitly differentiates from sibling scan_namespace ('Use scan_namespace instead when you already have an explicit list'), so an agent can route without opening either schema.

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

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

Gives explicit when-to-use triggers ('choosing or inventing a name', with sample user utterances), names the alternative (scan_namespace) and its selecting condition, and lays out a workflow chain (follow with score_name, check_live LAST as the purchase gate). Nothing is left to inference.

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

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

Annotations already carry readOnly=false, destructive=false, idempotent=false, so the description adds useful patch semantics rather than redisclosing safety. It explains omitted files are carried forward, previous versions are immutable, and the response includes the new version and preview_url. This clarifies behavior beyond a mere mutation label.

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?

Five short sentences, each with a distinct job: trigger, prerequisite, action, patch behavior, retention, return value. Front-loaded with the when-to-use condition, zero 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 2-param update tool with no output schema, the description fully covers invocation flow, versioning, and return value. An agent can call it correctly without needing additional information beyond the schema and 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 coverage is 0%, so the description carries the burden for the two parameters. It explains the lifecycle behavior of `files` (sent files become a version, omitted files carry forward), but it never names `draft_id` explicitly or gives structure for path/content; those are obvious from the schema but not documented in prose. Adequate compensation for a small, self-descriptive 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?

Clear verb+resource: 'Update files in an existing draft.' The phrase 'draft already exists' differentiates it from create_draft, and the mention of copy, sections or layout clarifies scope. No ambiguity.

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?

Explicit when-to-use: 'Use this when a draft already exists and the user asks to change its copy, sections or layout.' It also gives a concrete prerequisite: call get_draft first if current text isn't available, which routes the agent to the correct sibling.

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 provide idempotentHint and non-destructive context, but the description adds valuable behavior: start returns a TXT record, check verifies it, failed DNS lookup returns an error rather than 'not owned', and verification gates list_domains. These are meaningful behavioral details beyond 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?

Every sentence earns its place: the trigger condition, the core mechanism, the action distinction, the list_domains dependency, and the error semantics. It is front-loaded with the most important usage guidance and avoids 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 two-parameter tool with no output schema, the description covers the necessary workflow, return behaviors, and a key error case. It also connects the tool to the broader system state via list_domains, making it complete enough for an agent to invoke 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 only 50%, but the description compensates by explaining what each action does: 'start' returns the TXT record and 'check' verifies it. The domain parameter is self-evident from context. The description adds real meaning to the action enum beyond the schema's default note.

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: proving domain ownership via a DNS TXT challenge, with two explicit actions. It also distinguishes itself by explaining that verification is required before a domain appears in list_domains, differentiating it from sibling domain-related tools.

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

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

Explicitly says to use it when the user claims a domain is theirs and the agent is about to act on that claim. It also provides workflow guidance (start then check) and states the prerequisite relationship to list_domains, which serves as clear when-to-use context.

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