deSEC MCP by usefulapi

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

Although annotations already declare destructive=false/readOnly=false, the description adds critical context the annotations cannot: changes go live in DNS immediately, a wrong record can take a site or mail offline, it never touches apex NS or DNSSEC records, and it cannot delete anything. It also discloses concrete write rate limits (15/min, 300/day per domain).

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 'WRITE:' so a scanning agent immediately sees the risk class, then packs failure modes, side effects, restrictions, and rate limits into a few dense sentences. No filler and no repetition of what the schema or annotations already say.

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 non-idempotent, destructive write with no output schema, the description supplies the failure conditions, the immutability boundaries (NS/DNSSEC untouched, cannot delete), the rate limits, and the conflict semantics. An agent has everything needed to decide and invoke safely.

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 real interpretive value by explaining that the uniqueness key is the combination of subname and type, and the destination endpoint POST /domains/{name}/rrsets/. It stops short of restating ttl/records formatting, which the schema already 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 ('create ONE new RRset') and immediately defines the domain concept in parentheses, so the agent knows exactly what object is produced. It also distinguishes itself from the sibling desec_replace_rrset by naming the failure mode that routes there.

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 routing: 'Fails if an RRset with this subname and type already exists (use desec_replace_rrset for that).' It also states when it will fail on CNAME conflicts, giving clear when/when-not guidance rather than leaving the agent to guess between create and replace.

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 (readOnly, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior the annotations don't carry: the expensive-operation rate limit (300/min) and the underlying GET endpoint. It doesn't discuss response size or pagination for large zones, keeping it from a 5.

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

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

Three tight sentences with the scope stated first and the practical backup note and rate limit following. Every sentence carries information; nothing is wasted 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?

For a read-only export with annotations carrying the safety profile, the description explains the return format (plain-text BIND zonefile), the scope exclusion (DNSSEC types), and the cost (rate limit). An agent has everything needed to call it correctly.

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

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

The single 'domain' parameter is fully documented in the schema (100% coverage), so the schema does the heavy lifting. The description adds only the endpoint path showing where the name goes, not new semantics. 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 (export) and resource (the whole zone as a BIND-format zonefile), and pins the scope precisely: 'all RRsets except DNSSEC types.' This clearly distinguishes it from siblings like desec_get_rrset or desec_list_rrsets, which operate at the RRset level rather than the whole zone.

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?

'Handy as a backup before changing records' gives an explicit when-to-use context, which is more than most tools offer. It doesn't name a sibling alternative or an exclusion case, so it falls short of a full 5.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context about the returned data (DNSSEC key material, DNSKEY and DS records, minimum TTL, publication times), though it does not discuss auth requirements, error behavior, or rate 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?

The description uses two efficient sentences, front-loading the return contents and then giving the endpoint. No filler or redundant text is present.

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 lookup with one well-documented parameter and no output schema, the description adequately explains the return payload and endpoint. It omits usage guidance and error/not-found behavior, but the annotations cover the safety context.

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

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

Schema description coverage is 100%, and the single 'domain' parameter is fully documented in the schema with an example and a reference to desec_list_domains. The description adds no syntax or format detail beyond the endpoint path, so the baseline of 3 applies.

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

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

The description clearly identifies the resource (one domain) and its DNSSEC-specific contents (DNSKEY, DS records, TTL and publication times), and it includes the concrete GET /domains/{name}/ endpoint. This distinguishes it from siblings like desec_list_domains (plural) and the rrset-focused 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?

The description gives no guidance on when to use this tool versus alternatives such as desec_list_domains or desec_get_rrset. It only describes the return payload and endpoint, leaving the agent to infer usage conditions.

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes the REST endpoint shape (GET /domains/{name}/rrsets/{subname}/{type}/), which aids traceability, but adds nothing about auth requirements, rate limits, or behavior on a non-existent RRset.

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: the purpose and examples come first, the endpoint fragment last. 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 no output schema, the description should say what comes back (the RRset's records/TTL, error on missing RRset) and that subname is optional, but it does not. It is functional for invoking the call yet leaves the return contract to inference.

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 itself documents type, domain and subname in detail (including '@'/empty for apex). The description's examples restate rather than extend that, 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?

States a specific verb and resource (get one RRset) and clarifies the granularity with worked examples ('the A records of "www"'), implicitly distinguishing it from desec_list_rrsets. It never explicitly names the sibling, however, so an agent must infer that this is the single-item counterpart.

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

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

Usage is implied by the worked examples of address/MX lookups, but there is no explicit 'use this when you know the exact subname and type, otherwise use list_rrsets' guidance or any prerequisite statement. Moderate gap for a read tool sitting next to desec_list_rrsets.

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 (readOnly, non-destructive, openWorld), and the description adds real substance on top: result ordering, the fields returned, that DNSSEC keys are omitted, the 500-per-page cap, and the underlying GET /domains/ endpoint. This is meaningful context beyond the structured hints.

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 core purpose and scope, then layers ordering/fields, the sibling pointer, the parameter guidance, the page limit, and the endpoint. Every sentence carries information and nothing is redundant.

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

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

With no output schema, the description still describes the return shape (creation time, last-published time, minimum TTL) and pagination behavior (cursor, up to 500 per page), while annotations cover the read-only/open-world profile. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters (baseline 3). The description nonetheless adds interpretive value by explaining the intent behind owns_qname (longest matching zone you own) and giving a motivating example, going past what the schema's own text conveys.

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 domains/zones) scoped to 'this deSEC account', plus ordering ('newest first') and returned fields. It explicitly distinguishes itself from the sibling desec_get_domain by naming where DNSSEC keys live, so an agent can route without opening the schema.

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

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

Provides a concrete when-to-use for the owns_qname parameter ('find which of your domains is responsible for a DNS name... before adding a record for www.dev.example.net') and redirects to desec_get_domain for the omitted DNSSEC keys. Clear context, though it doesn't state when NOT to list (e.g. single-domain lookups beyond the DNSSEC case) with the same precision.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: newest-first ordering, a 500-per-page cap, and the RRset grouping rule. It does not mention rate limiting or auth requirements, but that is a minor gap given the annotation coverage.

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 short sentences, each earning its place: purpose and RRset definition front-loaded, then filtering, then pagination, then the endpoint. No filler or redundancy.

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

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

With no output schema, the description carries the burden of describing returns, and it does so reasonably by defining an RRset and noting newest-first order and page size. It omits what fields each returned RRset carries (ttl, records, type, subname), which is the only notable gap for a list tool.

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

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

Schema description coverage is 100%, so all four parameters (type, cursor, domain, subname) are already well documented in the schema, including the cursor's next_cursor origin and the '@' apex convention. The description only restates the type/subname filters and adds no format or syntax detail beyond the schema. Baseline 3 is correct.

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 gives a specific verb (List) and resource (DNS records of a domain as RRsets) and even defines what an RRset is — 'all records of one name and type, sharing one TTL' — which cleanly separates it from desec_get_rrset (singular). It stops short of naming or contrasting any sibling explicitly, 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?

It states that you can 'Filter by type and/or subname' and the schema notes omitting subname includes every subname, so usage is implied. There is no explicit when-to-use-this-vs-alternatives guidance (e.g., list vs get_rrset vs export_zonefile), leaving the agent to infer.

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/idempotentHint, but the description goes further: it discloses immediate DNS propagation risk, that the prior RRset is read and returned as `previous` for undo, the refusal of empty record lists, immutable apex NS/DNSSEC, rate limits, and the underlying PUT endpoint shape.

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

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

A single dense paragraph, front-loaded with the destructive WRITE marker and the exact effect, then risk, reversibility, failure modes, limits. No sentence is 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 destructive, no-output-schema write tool, the description covers effect, reversibility (previous returned), failure conditions, protected records, and quotas. An agent has everything needed to call it safely without additional context.

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 ttl, records, subname, and type semantics are already documented in the schema. The description adds only the one-element-array/PUT framing and the `previous` return behavior, so the 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 precise verb+resource+scope: 'set ONE RRset to exactly the given TTL and records'. This distinguishes it from desec_create_rrset (create-only) and desec_get_rrset/desec_list_rrsets, and the WRITE (overwrites) marker front-loads the operation class.

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

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

Gives clear context: creates if absent, replaces if present, refuses empty lists, cannot touch apex NS/DNSSEC, and cites write limits (15/min, 300/day). It does not explicitly name desec_create_rrset as the alternative when you only want to add without replacing, which is the one routing gap.

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