domeneshop-mcp

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description's only addition is the return shape ('the stored record, including its new ID'), which is useful since no output schema exists, but it omits conflict/duplicate behavior for a non-idempotent write.

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, zero filler, with the core action front-loaded and the return behavior second. Nothing is wasted.

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 15-parameter write tool with heavy type-dependent requirements, the schema carries the parameter burden and annotations carry the safety profile, so the definition is callable. It is thin on the two things structured data cannot supply: how this differs from upsert_dns_record, and what happens on a duplicate host/type.

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 every parameter — including the type-conditional ones (usage/dtype/selector for TLSA, alg/digest for DS, port/weight/priority for SRV) — is already documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline 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?

States a specific verb and resource ('Create a new DNS record for a domain') and adds a return-value clause. It does not name or contrast with the closest sibling, upsert_dns_record, leaving the agent to infer the create-vs-upsert distinction from names alone.

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

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

No when-to-use guidance and no exclusions. The critical routing question for this tool family — create vs upsert_dns_record vs update/patch_dns_record — is left entirely to inference, and nothing is said about what happens if the record already exists.

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 establish the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful behavioral context beyond that: the operation fails if the host already has a forward or a conflicting A/AAAA/ANAME/CNAME record, which tells the agent about uniqueness/conflict preconditions.

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 action and followed by the failure condition. No wasted words and appropriately sized for the tool's complexity.

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

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

For a 4-param create tool with a fully documented schema and mutation annotations, the description covers purpose and the conflict failure mode. Missing details like permission requirements or the return payload are minor since there is no output schema and annotations already convey the safety profile.

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 all four parameters (url, host, frame, domain_id) are already documented in the schema. The description adds no parameter-level 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 ('Create a new HTTP forward for a domain'), which is distinct from the many create_dns_record/create_* siblings. It doesn't explicitly name a sibling to contrast against, but the resource ('HTTP forward') is unambiguous.

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 implied use case (adding a forward) is clear from the verb, and the precondition that the host must not already have a forward gives some context. However, no alternatives are named (e.g. update_forward, create_dns_record) and there is no explicit 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description's 'This cannot be undone' merely reinforces destructiveHint without adding new context such as required permissions, confirmation behavior, or cascade effects on dependent records.

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 with zero filler, and the core action is front-loaded ahead of the warning. Nothing needs to be trimmed or moved.

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

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

For a simple two-parameter delete with a complete schema and annotations that already cover the destructive/idempotent profile, the description is essentially sufficient. It could go further by noting confirmation expectations or effects on related records, but nothing essential 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%: both domain_id and record_id are documented in the schema, including their provenance ('from list_domains' and 'from list_dns_records'). The description adds nothing about the parameters, so the baseline 3 applies with the schema doing all the work.

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

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

States a specific verb and resource ('Delete a DNS record'), so an agent immediately knows the action. It does not explicitly differentiate itself from sibling delete tools such as delete_forward or mutation tools like update_dns_record, so sibling routing is left to the name alone.

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 guidance on when to use this versus update_dns_record, patch_dns_record, or upsert_dns_record, nor any prerequisites or exclusions. The only caution is the irreversibility note, which is a warning rather than usage 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true. 'This cannot be undone' merely restates the destructive hint and adds no new context like auth requirements, side effects on related records, or confirmation 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?

Two short sentences, front-loaded with the action and followed by the key constraint. No padding or redundant explanation.

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 simple two-parameter delete operation, rich schema descriptions, and thorough annotations, the description is nearly complete. It confirms the purpose and irreversibility, though it omits guidance about related tools that an agent might consider first.

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 fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete an HTTP forward'), and the resource is clearly distinct from sibling tools such as delete_dns_record or delete_dyndns. An agent can identify the operation without opening the schema.

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

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

No explicit when-to-use, when-not-to-use, or alternatives are given. The name and purpose imply deletion, but the description does not distinguish this from other delete tools or state prerequisites such as owning the domain.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that — no note on missing/not-found behavior, cross-domain lookup constraints, or rate limits — so it contributes no behavioral context of its own.

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 short sentence with no wasted words and the resource front-loaded. It is arguably under-specified rather than bloated, but the structure itself is clean.

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

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

For a simple two-parameter read tool with an output schema and annotations covering safety and idempotency, the description covers the essential contract; return values need not be explained. The only gap is the absence of routing guidance versus list_dns_records.

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%, with both domain_id and record_id documented as coming from list_domains and list_dns_records respectively, so the schema does the heavy lifting. The description only alludes to 'by ID' and does not add format or provenance detail beyond the schema, which is the baseline 3 case.

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

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

States a specific verb (Get) and resource (a single DNS record) scoped by ID, which distinguishes it from the bulk sibling list_dns_records. It does not, however, name any sibling explicitly, so the differentiation is only implied by the word 'single'.

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 when-to-use guidance: the description never says to prefer this over list_dns_records when you already know the record ID, nor does it state any prerequisites. Usage must be inferred entirely from the name and schema.

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 openWorldHint. The description adds useful behavioral context by naming the returned fields (expiry, renewal, nameservers, active services), though it does not mention error behavior such as an invalid or missing domain 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?

A single, front-loaded sentence with no wasted words. The resource and identifier appear immediately, followed by the useful detail fields.

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

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

With one parameter, an output schema present, and annotations covering read-only/idempotent behavior, the description is nearly complete. The only minor gap is error or authorization behavior for invalid or inaccessible domain IDs.

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

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

The single parameter has 100% schema description coverage and is already documented as "the Domeneshop domain ID, from list_domains." The description restates that it takes a Domeneshop domain ID but adds no syntax or format details beyond the schema, so the baseline score 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?

Uses a specific verb+resource combination ("Get details for a single domain") and names the identifying key. The phrase "single domain" clearly contrasts with the sibling list_domains, so an agent can distinguish the scope without reading 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?

Makes clear this is for retrieving one domain's details and references the domain ID. It does not explicitly state when not to use it or name alternatives, but the single-item scope makes the intended context 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=true, idempotentHint=true, and openWorldHint=true, so the safety profile is fully covered structurally. The description adds nothing beyond them: it does not say what happens when no forward exists for the host, whether the lookup is case-sensitive, or anything else about 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?

A single tight sentence with the resource and scoping constraint front-loaded and zero filler. It is efficient, though it is arguably too sparse to be maximally useful.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. What remains missing is routing information relative to list_forwards and the not-found case, leaving the definition minimally viable but not complete.

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

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

Schema description coverage is 100% and both parameters are well documented in the schema (including the '@' root-host convention and the domain_id source). The description adds no parameter detail beyond what the schema already provides, 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 states a specific verb and resource ('Get the HTTP forward') and scopes it to a specific host, so the agent knows exactly what is retrieved. It does not, however, distinguish this tool from the sibling list_forwards, which is the most likely alternative an agent would consider.

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 guidance on when to use this versus list_forwards or get_domain, and no mention of prerequisites or error conditions. The agent must infer usage entirely from the name and the host parameter.

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 openWorld, so the safety profile is covered. The description adds genuinely new context by disclosing that the response includes a link to the PDF, which annotations and schema do not convey.

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

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

A single front-loaded sentence with no filler; the resource and the notable output detail are both packed in without waste.

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 and annotations covering safety, the description needn't explain return values, and it adds the one non-obvious detail (PDF link). It stops short of noting behavior for missing/invalid IDs, but for a simple getter this is close to complete.

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

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

Schema description coverage is 100% and the sole parameter is fully documented in the schema ('the invoice ID, from list_invoices'). The description adds no syntax or format detail beyond the schema, 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 (get) and resource (a single invoice), and the qualifier 'single' implicitly separates it from the list_invoices sibling. It does not name that sibling explicitly, so the differentiation is inferred rather than stated.

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 explicit when-to-use or when-not-to-use guidance is given. Usage is only implied by the schema (invoice_id 'from list_invoices'), which routes the agent adequately but leaves the description itself silent on context and 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 already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered without the description. The description adds the filtering scope, but says nothing about pagination, result volume, or ordering for what is inherently a list 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?

A single front-loaded sentence naming the verb, resource, scope and optional filters. No filler, no repetition of the 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?

An output schema exists, so return values need not be explained, and annotations cover the safety semantics. The only material gap is enumeration behavior (pagination/limits) for a list endpoint, which an agent may need before calling it against a large zone.

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 all three parameters are documented in the schema, so the baseline is 3. The description restates the host and type filters without adding format or syntax detail (e.g. that '@' means apex, or that ''/empty type means all types) beyond what the schema already carries.

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 (List) and resource (DNS records) with an explicit scope (for a domain), so the agent immediately knows it is a read/list operation. It does not explicitly differentiate itself from the sibling get_dns_record or from list_domains, but the resource is unambiguous.

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

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

The phrase 'optionally filtered by host and/or record type' implies the usage context (enumerate or narrow a record set) but never states when to use this versus get_dns_record for a single record or list_domains for enumeration. No exclusions or prerequisites are given.

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 openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that — that the call enumerates all domains and serves as the prerequisite lookup for domain_id — though it says nothing about return volume or account scoping limits.

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

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

Two tight sentences with zero filler. The core purpose is front-loaded and the actionable usage hint follows immediately.

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. Purpose, optional filtering, and the prerequisite role are all covered, and annotations handle the safety profile — 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?

Schema description coverage is 100%, so the single filter parameter is already fully documented in the schema. The description mirrors this ('optionally filtered by domain name') without adding syntax or matching semantics beyond the schema. 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 (List) and resource (domains) with scope ('on the Domeneshop account') and an optional filter, cleanly distinguishing it from the singular sibling get_domain. An agent can tell immediately what it returns 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?

Provides clear when-to-use context: 'Use this first to find the domain_id the other tools need,' establishing it as the prerequisite/entry point for the DNS and forward tool families. It stops short of naming a specific alternative (e.g. get_domain for a single domain's detail), so it is strong but not fully explicit.

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 openWorldHint=true, so the safety and side-effect profile is covered. The description adds nothing beyond that - no mention of pagination, ordering, or behavior when a domain has zero forwards - which is acceptable given annotations but adds no extra 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?

One short sentence, front-loaded with the verb and resource, with no filler or redundancy. Nothing in it fails to earn its place.

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

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

For a read-only single-parameter list tool with an output schema (so return values need no explanation) and full parameter documentation, the description is nearly sufficient. A brief note on empty results or the relationship to get_forward would have closed the remaining gap.

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

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

There is a single required parameter and schema description coverage is 100%, with the schema even documenting that domain_id comes from list_domains. The description adds no meaning beyond the schema, 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 (List) and resource (HTTP forwards) plus a scope qualifier (configured for a domain). It is clear what the tool returns, but it never distinguishes itself from the sibling get_forward or from the broader list_dns_records family, so it lands at 4 rather than 5.

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

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

The phrase 'configured for a domain' implies the usage context (you need a domain in hand), but there is no explicit when-to-use guidance, no statement of when not to use it, and no pointer to get_forward for fetching a single forward. Usage is inferred, not 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 already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are limited to the past three years — but says nothing about pagination, result caps, or ordering. Comparable to the calibration case that scored 3 for a date-range scoping note without return-format 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?

A single sentence that front-loads the resource and its scope before the optional filter. Nothing is padded or repeated.

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 single optional parameter is fully documented in the schema. The only real gap is pagination/result-size behavior for what could be a multi-year invoice list.

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 schema itself carries the important nuance ('settled' applies only to credit notes). The description only restates that status filtering exists, adding no syntax or semantics beyond the schema, 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 (List) and resource (invoices), plus a concrete scope: the past three years on the Domeneshop account. It distinguishes itself implicitly from get_invoice by the 'list' verb, but never names a sibling or clarifies how it relates to get_invoice.

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

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

The phrase 'optionally filtered by status' implies when the parameter should be supplied, but there is no guidance on when to reach for this tool versus get_invoice, nor any stated exclusions or prerequisites. Usage is inferable 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 already declare idempotentHint=true, destructiveHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the read-merge-write behavior ('current record is read first and every field you leave out keeps its stored value') and the return ('Returns the stored record').

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 partial-update behavior, then the merge semantics, then the sibling routing. Every sentence carries distinct information with no 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?

Signals the return value ('Returns the stored record') even though no output schema exists, and the schema fully documents the 16 parameters. For a partial-update mutation the description is essentially complete, with only the absence of an explicit when-not statement as 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 coverage is 100%, so every one of the 16 parameters is already documented in the schema, making the baseline 3. The description only reinforces this with the 'e.g. just data or ttl' example, adding no format or constraint detail the schema lacks.

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 ('Change only some fields of an existing DNS record') and pinpoints the partial-update semantics with 'e.g. just data or ttl', clearly distinguishing it from the sibling update_dns_record. An agent can tell patch from update and create without opening a 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 routes the agent: 'Prefer this over update_dns_record' names the alternative and the condition (partial vs. full change). It does not state when update_dns_record would be the better choice, so the exclusion side is left implicit rather than fully spelled out.

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 flag destructiveHint, non-readonly and idempotent, but the description adds the operationally critical detail that this is a full overwrite: omitted fields are dropped and a missing ttl silently resets to 3600. That is behavior an agent cannot infer from the hints alone.

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 destructive overwrite semantics, then the alternative, then the return. No filler and every sentence carries decision-relevant information.

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

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

For a 16-parameter destructive mutation with no output schema and full schema coverage, the description supplies exactly the missing piece: overwrite semantics and the routing rule. Return behavior is stated in one clause, which suffices absent an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the requirement to send every field that should be kept, and the default-reset consequence of omitting ttl. It stops short of explaining the per-type conditional fields (which the schema covers).

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 ('Replace an existing DNS record') and immediately distinguishes it from the sibling patch_dns_record, which handles partial updates. An agent can pick between update/patch/upsert 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 an explicit when-not rule with the alternative named: 'To change only some fields, use patch_dns_record instead.' Combined with the overwrite warning, this routes the agent correctly among the create/patch/upsert/update siblings.

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 non-readOnly, destructive, idempotent and openWorld, so the safety profile is covered. The description adds value beyond them by disclosing upsert semantics ('a missing record is created, an existing one overwritten') and that the A/AAAA type is derived automatically, which is not in the annotations. It still omits auth/credential and failure 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?

Two sentences, zero filler, front-loaded with the action and followed by the record-type/upsert behavior. Every clause carries information.

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

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

For a 2-parameter mutation with no output schema, 100% schema coverage and rich annotations, the description covers the core behavior an agent needs. It is slightly thin on prerequisites (dynamic-DNS credentials) and return shape, which the lack of an output schema pushes onto prose.

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 fully documented (comma-separated lists, IPv4/IPv6, caller's apparent IP fallback). The description mostly restates 'the given (or the caller's apparent) IP address,' adding only the minor inference that record type follows from address form. Baseline 3 is appropriate.

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

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

States a concrete verb+resource+mechanism: 'Point one or more hostnames at ... IP address using Domeneshop's dynamic DNS protocol.' An agent immediately knows the action and the protocol context. It does not, however, distinguish itself from the near-identical siblings update_dns_record and upsert_dns_record, so sibling differentiation is left implicit.

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 when-to-use/when-not guidance and no alternative named, even though update_dns_record and upsert_dns_record are siblings with overlapping effect. The description only implies usage through its purpose statement; nothing routes the agent between these tools or mentions dynamic-DNS credential prerequisites.

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 destructive, idempotent, and open-world behavior. The description adds critical behavioral context: `frame` resets to false unless provided, the `host` cannot be changed, and the tool returns the stored forward. It doesn't describe authentication or rate limits, but adds enough beyond 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?

Four tight sentences, front-loaded with the core action and return value. Each sentence (purpose, return, frame reset, host immutability/alternative) adds distinct value with no 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?

With annotations covering destructive/idempotent/open-world traits and full schema descriptions, the description fills remaining gaps: return value, frame reset semantics, and host immutability. It could clarify why `host` is required if immutable, but it is largely complete for correct invocation.

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

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

Schema coverage is 100% and already documents each parameter. The description adds a key constraint not in the schema: `host` cannot be changed, and reinforces the `frame` default reset behavior. This extra meaning justifies above the 3 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?

States a specific verb 'Update' and resource 'HTTP forward', with scope 'existing' and 'for a domain'. This clearly separates it from create_forward, delete_forward, and get_forward siblings 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?

Description says to use this for existing forwards and explicitly directs 'to move a forward, delete it and create it again' for host changes, providing an alternative. However, it doesn't state when to use update_forward versus other siblings like patch or upsert, or any prerequisites beyond the 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?

Beyond the annotations (idempotentHint/destructiveHint/openWorldHint), the description discloses merge semantics ('optional fields you leave out keep their stored value'), atomic failure behavior ('Fails without changing anything'), and the return shape. These are exactly the behavioral facts annotations cannot convey for a partially-destructive upsert.

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?

Four tight sentences, front-loaded with the upsert semantics and ordered by likelihood of need: what it does, update merge behavior, failure case plus alternatives, return shape. No 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 15-parameter tool with 100% schema coverage and no output schema, the description supplies the missing pieces: the uniqueness/failure precondition, the alternative routes, and the return payload. Nothing an agent needs to call this correctly is 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. The description adds real value on top: it clarifies that omitted optional fields such as ttl and priority retain stored values on update rather than reverting to schema defaults, and it introduces the record_id parameter that lives in patch_dns_record.

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+resource+scope: 'Make sure a host has exactly this record of the given type: updates the existing record for that host and type, or creates one if there is none.' An agent can distinguish it from create_dns_record, update_dns_record, and patch_dns_record 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 defines the failure condition (host already has several records of that type, common for MX/TXT) and routes the agent to named alternatives: patch_dns_record with a record_id, or create_dns_record to add another. Both when-to-use and when-not-to-use are covered.

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