NS1 Connect MCP by usefulapi

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

Annotations mark this destructive and open-world, but the description goes well beyond them: it warns the change goes live as soon as NS1 serves it and that a wrong answer can take a site or mail offline. It also discloses the existence check and refusal behavior, which no annotation conveys.

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 write/live-DNS risk, then the scope limits, then the alternative, then the rdata formats. Every clause carries information, including the PUT endpoint, and the example lists are compact rather than padded.

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

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

For a destructive, no-output-schema mutation tool this covers the risk, the type boundary, the conflict behavior, the alternative tool, and the exact rdata shapes an agent must construct. Nothing needed 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 coverage is 100%, so the baseline is 3, but the schema defers the hardest parameter to the description ('each a list of rdata fields (see the tool description)'), and the description pays that off with concrete per-type examples for A, MX, TXT, SRV, and CAA. That is real added meaning, though ttl and zone/domain formatting are left to the 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?

Opens with a specific verb and resource ('WRITE: creates ONE new DNS record') and immediately scopes the effect ('CHANGES LIVE DNS for that name'). It distinguishes itself from the sibling ns1_update_record by naming it in the refusal case, so an agent can route correctly without reading 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?

States explicitly when it refuses ('when the record already exists') and names the correct alternative ('use ns1_update_record'). It also bounds applicability by listing supported record types and explicitly excluding NS/SOA and traffic-steering filters/metadata, so the when-not is as clear as the when.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds the endpoint path and the content scope, but discloses nothing beyond that — no auth requirements, rate limits, or freshness/caching 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 tight sentences with no filler; the content scope is front-loaded and the endpoint is appended last. The trailing REST path is marginally redundant for an MCP caller but does not bloat the definition.

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 telling the agent what comes back, and it does name the returned areas (subscription, resources, utilization versus plan limits). It is a bit thin — the trailing ellipsis and lack of structure leave some ambiguity about exact fields — but it is adequate for a zero-parameter read-only tool.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. No parameter-level explanation is required or missing.

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

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

The description names a specific resource (the account) and enumerates what the summary contains — subscription, resources, utilization against plan limits — which lets an agent distinguish it from the narrower siblings like ns1_get_usage_stats or ns1_get_billing_queries. The verb is only implied via the title and the trailing 'GET /v1/account/summary', so it stops just short of a full verb+resource statement.

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 only implied: calling a 'summary' tool suggests a high-level overview, but the description never says when to prefer this over ns1_get_usage_stats, ns1_get_billing_queries, or ns1_get_qps_stats, nor does it state any preconditions. There is no explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying REST path (GET /billing-usage/v1/queries), which confirms a direct read call, but says nothing about auth scope, rate limits, or result granularity — acceptable but not rich.

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 waste, with the core purpose and the time-window constraint front-loaded. The raw endpoint path is a minor redundancy but does not dilute the front-loaded structure.

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

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

There is no output schema, so the description would ideally indicate what comes back (query counts, per-period breakdown) and whether results are aggregated. For a two-parameter, fully documented read call the definition is minimally adequate, but the return-value gap is a real omission.

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 (from/to, Unix seconds) are fully documented in the schema, so the baseline is 3. The phrase 'between two Unix timestamps' merely restates the schema's unit and range semantics rather than adding format or boundary details.

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

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

The description names a specific verb+resource (billable DNS query usage) and its scope (between two Unix timestamps), which is enough for an agent to grasp the operation. However, it does not differentiate from the closely related sibling ns1_get_billing_records or ns1_get_usage_stats, leaving ambiguity about which billing/usage endpoint to pick.

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 only implied by the subject matter: an agent can infer this is for billable query metering over a time window, but there is no explicit when-to-use, no exclusions, and no pointer to ns1_get_billing_records or ns1_get_usage_stats 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile needs no restating. The description adds the meaningful scoping detail that the figure covers only the current billing cycle, but says nothing about aggregation scope (sub-accounts, zones) or response 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?

Two short sentences, front-loaded with the metric and its scope. The trailing endpoint path is mildly redundant but compact and unambiguous.

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 and no parameters, the description is the only source for what comes back, and it does not indicate the response fields (used count, plan limit, percentage) or the aggregation basis. Adequate for a simple metric getter, but a clear gap remains.

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 of 4 applies. There is no argument syntax an agent could get wrong.

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 metric ('How many DNS records the account uses against its plan limit') scoped to the current billing cycle, which distinguishes it from ns1_get_billing_queries and ns1_get_usage_stats by resource. It never names a sibling explicitly, so 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?

Usage is implied by the billing-cycle framing — an agent can infer this is for the records-quota check — but there is no explicit when-to-use guidance, no mention of when to prefer ns1_get_billing_queries or ns1_get_usage_stats, and no prerequisites 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the hierarchy (feed belongs to a source) and the REST route, but says nothing about failure modes when a feed id is invalid or about the shape of the returned feed, leaving behavioral gaps 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?

Two short sentences, front-loaded with the purpose; the second sentence provides the route mapping efficiently. It is close to minimal, though the route literal is mostly echo for an agent that already sees the tool metadata.

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

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

There is no output schema, so the description would ideally hint at what a feed object contains or errors on missing ids; it does not. For a simple two-parameter read with full schema coverage, however, the core retrieval semantics are complete enough to call 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%, so both source_id and feed_id are already documented with type, pattern, and length constraints. The description only restates the id-based lookup relationship (feed within a source), adding little 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-plus-resource ('Get/One data feed of a source by id') and adds the exact REST route, so an agent can distinguish it from ns1_list_data_feeds and ns1_get_data_source. It lacks an explicit 'not the list version' contrast, but the 'one ... by id' phrasing already separates it from the list sibling.

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, no prerequisites, and no named alternative (e.g., use ns1_list_data_feeds to discover feed ids first). The single-fetch intent is only implied by 'by id' and the path template.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value by disclosing that connection settings and credentials are redacted and that feeds are embedded in the response — details the annotations 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?

Three tight sentences with the core purpose front-loaded, then the redaction caveat, 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 usefully signals what comes back (the source plus its feeds, minus credentials), which is what an agent needs to decide to call it. Minor gaps remain around error behavior for an unknown id, but coverage is solid for a simple read.

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?

With 100% schema coverage and a single parameter, the schema already carries the id format, pattern, and origin. The description's 'by id' restates the schema rather than adding syntax or edge-case meaning, 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 (get one data source by id) and adds scope detail — the response includes its feeds. This clearly separates it from ns1_list_data_sources and ns1_get_data_feed without needing to open 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?

The phrase 'by id' implies single-item lookup, and the schema points to ns1_list_data_sources as the id source, but the description itself never states when to use this versus the list or feed siblings. Usage is implied rather than 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not carry: credentials and header values are redacted in the response, which tells the agent not to expect secret material back.

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 terse sentences plus the endpoint path, front-loaded with the resource and payload contents. Every clause carries information: what is returned, what is redacted, and the underlying route.

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 tool with no output schema, the description adequately covers what comes back and the redaction caveat, while annotations handle safety. Minor gaps remain (error behavior for a nonexistent id, whether the endpoint is paginated), but nothing an agent needs to invoke 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?

There is a single parameter (job_id) with 100% schema description coverage, including pattern and length constraints plus provenance guidance. The description adds no syntax, format, or validation detail beyond the schema, 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?

The description states a specific verb and resource: fetch one monitoring job by id, and enumerates the returned surface (configuration, rules, regions, status). 'One ... by id' implicitly separates it from the list-style sibling ns1_list_monitoring_jobs, though it never names that sibling explicitly, so it falls just short of a 5.

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

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

Usage is only implied: the agent infers it should call this when it already has a job id, and the input schema's note ('from ns1_list_monitoring_jobs') supplies the only routing hint. The description itself gives no when-to-use, when-not-to-use, or alternative selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint path and the scoping hierarchy, but says nothing about freshness/lag of the 'current' metric, rate limits, or what the response contains.

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 resource and scope before the endpoint detail. The raw path is arguably redundant with the prose but it efficiently communicates the nesting, so little 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 stats read endpoint whose safety profile is fully covered by annotations, the description covers scope and parameter combinations adequately. With no output schema, it could have said more about the returned shape (single number vs per-zone breakdown), which is the only notable 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 the baseline is 3, but the description adds a real semantic the schema lacks: the valid parameter combinations. The schema shows all three params as independent optionals, while the description makes clear that domain/type are only meaningful together with zone.

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 ('current queries per second') and enumerates the three aggregation levels (account, zone, record). It is distinguishable from siblings like ns1_get_usage_stats and ns1_get_billing_queries via the word 'current', but it never names those alternatives to sharpen the distinction.

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 parenthetical '(give zone, or zone + domain + type)' tells the agent which parameters select which granularity, which is genuine usage guidance. However, there is no statement of when this tool is preferable to the other stats tools (usage_stats, billing_queries), and no exclusions or 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful context by listing the fields returned (TTL, answers, filter chain, linked record, region settings), but does not disclose any behavioral traits beyond annotations such as error handling, auth requirements, 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?

Two sentences with zero waste: the first front-loads the purpose and enumerates return fields, the second gives the exact HTTP endpoint. Every element is informative and appropriately sized for a simple getter.

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-record GET tool with full schema coverage and safety annotations, the description is complete: it identifies the resource, lists key return fields (compensating for the lack of an output schema), and provides the underlying endpoint. No critical operational detail 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 all three parameters (zone, domain, type) are already fully documented in the schema. The description simply restates that the record is identified by zone, domain, and type, adding no additional meaning or format details beyond what the schema provides.

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 specific resource ('one DNS record') and the three scoping parameters (zone, domain, type), and lists the returned fields. It implicitly distinguishes itself from list operations with 'One', but does not explicitly name a sibling alternative for contrast.

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 provides no when-to-use guidance, no alternatives, and no conditions under which this tool should be preferred over sibling tools like ns1_list_zones or ns1_get_zone. Usage is only inferable from the required parameters and the endpoint.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, and the description adds genuinely useful behavior: the conditional parameter applicability per granularity level, the period window options, and the pagination follow-up rule for next_page. It does not describe return shape or rate limits, but for a read-only stats endpoint this is solid added context.

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

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

Dense but front-loaded: the reporting scope comes first, then parameter constraints, then pagination, then the endpoint. Slightly run-on in the middle clause listing aggregate/expand/limit/after, but no wasted 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?

For a read-only, zero-required-parameter stats tool with no output schema, the description covers scope selection, parameter applicability per level, pagination handling, and the concrete endpoint. An agent has everything needed to construct a correct call at all three granularities.

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 level-scoping semantics the schema alone leaves implicit: aggregate/limit/after are meaningless for record-level queries, and period accepts only 1h/24h/30d. The path template (GET /v1/stats/usage[/{zone}[/{domain}/{type}]]) also clarifies how zone/domain/type compose.

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 (DNS query counts) and enumerates the three scopes it can report on (whole account, one zone, one record) with the parameter combination that selects each. However, it never contrasts itself with the nearby stats sibling ns1_get_qps_stats or ns1_get_account_summary, so an agent must infer the boundary between usage and QPS/summary statistics.

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 concrete conditional rules: "give zone, or zone + domain + type" to reach record granularity, and states that aggregate/expand/limit/after apply only at account and zone levels ("a record takes just period"). It also instructs the agent to re-call with next_page.after/limit when next_page is non-null. No explicit when-not or alternative-tool guidance, so short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower, and the description still adds real value: pagination contract via next_page and that TSIG secrets are redacted. It stops short of noting rate limits, auth requirements, or error/not-found 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 dense sentences with the payload shape first and paging behavior second, zero filler; the trailing 'GET /v1/zones/{zone}.' is marginal but harmless. Front-loading is good.

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

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

With no output schema, the description carries the return-value burden and does so well: record fields, paging loop, and redaction are all stated. An agent has everything needed to call and loop this endpoint 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%, and the schema already explains that after/offset come from next_page in the prior reply, so the description largely restates the schema. Baseline 3 is appropriate given the schema does the heavy lifting for all four 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?

States a specific verb+resource ('One zone with its settings and its record list') and even enumerates the shape of the returned records (domain, type, TTL, answers, linked/tier). The singular 'one zone' implicitly separates it from ns1_list_zones, and the record payload description separates it from ns1_get_record.

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 operational guidance for paging ('if next_page is not null, call again with its after/offset'), which tells the agent when to re-invoke. It does not, however, name alternatives such as ns1_list_zones for enumerating zones or ns1_get_record for a single record, so routing is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by naming the response fields (id, name, settings) and the underlying endpoint, but says nothing about pagination, result limits, or behavior for an unknown/empty source_id. Some added context, so above baseline but not rich.

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: the purpose/scope/return fields come first, the endpoint last. Nothing is redundant or padded, and the most decision-relevant information is front-loaded.

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 one-param read tool with full annotation coverage and no output schema, listing the returned fields is enough for an agent to call it correctly. The only minor gap is absence of any note on pagination or result size, which the absent output schema leaves unaddressed.

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 source_id parameter, and the description adds only the implied path placement (GET /v1/data/feeds/{source_id}), which duplicates structured information. With one well-documented param and no syntax gaps, 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 (List) and resource (feeds of one data source), and adds a genuinely useful gloss on what a feed is ('each feed is one monitored item, e.g. one server's health'). It distinguishes itself from single-feed retrieval by the plural scope, though it never names the sibling tools (get_data_feed, list_data_sources) to make the contrast explicit.

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

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

The scoping phrase 'of one data source' implies you must already have a source_id and want its child items, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as list_data_sources or get_data_feed. 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 readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value beyond that by disclosing that connection settings and credentials are redacted in the response. It does not discuss pagination or rate limits, which keeps it short of a 5.

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

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

A single front-loaded sentence carries the purpose, the parenthetical definition, the returned fields, the redaction caveat, and the underlying endpoint. Dense but not padded; the field enumeration is the only element that could be argued as over-specified for a no-arg list call.

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

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

With no output schema, the description usefully compensates by enumerating the returned shape (id, name, source type, status, feeds) and flagging redacted credential fields, giving the agent enough to act on the result. Minor gaps: no ordering, pagination, or volume expectations.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify beyond confirming it is a bare list operation with no filtering inputs.

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

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

States a specific verb and resource ('List the data sources') and immediately defines what a data source is ('connections to third-party monitoring or custom push sources used for traffic steering'). This distinguishes it from ns1_get_data_source (singular fetch) and ns1_list_data_feeds.

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 plural 'List' naming versus sibling ns1_get_data_source, and the endpoint is given, but there is no explicit statement of when to prefer this over ns1_get_data_source or ns1_list_data_feeds, nor any prerequisites noted.

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 read-only, non-destructive safety profile, but the description adds genuinely useful context beyond them: that request header values and credentials are redacted in the response, and the underlying GET endpoint. It stops short of noting pagination or result-size limits for a potentially large list.

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 resource and enumerating the returned fields, closed by the endpoint. No filler, and the enumeration earns its place because there is no output schema.

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, describing the returned fields (id, name, type, regions, frequency, rules, status, active flag, notify list id) plus the redaction caveat makes the tool callable and interpretable. The only real gap is absence of any pagination or ordering note for a list endpoint.

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 per the rubric the baseline is 4; there is nothing parameter-related the description needs to compensate for, and it correctly spends no space on input.

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 the account's NS1 monitoring jobs') and immediately clarifies what they are (health checks feeding traffic steering), which cleanly distinguishes it from the singular sibling ns1_get_monitoring_job.

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 plural-vs-singular contrast with ns1_get_monitoring_job is implied by the field-list framing, but the description never explicitly says when to use this versus fetching a single job or how it relates to other list tools. 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior: sensitive notifier settings (webhook URLs, tokens, service keys, addresses) are redacted, which an agent cannot infer from annotations or schema.

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

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

Three tight sentences, front-loaded with the resource and return fields, then the redaction caveat, then the endpoint. Each sentence carries information; only the trailing 'GET /v1/lists' is marginal.

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 must explain return values, and it does (id, name, notifier types, labels, redaction). It lacks any pagination or volume guidance, which is a minor gap for a list endpoint.

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

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

There are zero parameters, so the baseline is 4. The description correctly describes what the call produces rather than pretending to take input, aligning with the empty 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?

Specific verb 'List' plus resource 'notifier lists', and it names the exact fields returned (id, name, notifier types, labels). It distinguishes itself from the sibling get_* tools by being a collection lister rather than a single-resource fetcher.

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 grounds the tool by tying it to 'monitoring alerts' being sent to notifier lists, giving implied usage context. However, it never states when to use this versus the sibling list tools, nor any prerequisite or exclusion.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavior on top of that: the pagination loop via next_page.after/offset and the shape of returned zone records. It stops short of auth/rate-limit or default page-size details.

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 compact sentences that are front-loaded with the resource and returned fields, then the pagination rule, then the endpoint. 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?

For a low-complexity, parameterless list tool with no output schema, the description compensates by enumerating returned fields and explaining the pagination cursor flow, which is everything an agent needs to call and iterate 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%, and the schema already explains limit (1-1000, omit for default) and the after/offset cursors. The description's 'call again with its after/offset' restates the schema rather than adding format or edge-case detail, 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 ('List the DNS zones in the account') and enumerates what each entry contains (name, id, TTL/SOA settings, primary/secondary setup, linked zones, tags). This clearly separates it from the singular sibling ns1_get_zone and from the search tools, and the trailing 'GET /v1/zones' pins the resource precisely.

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 operational rule: 'If next_page is not null, call again with its after/offset to get more,' which tells the agent exactly how to continue an incomplete listing. It does not, however, say when to prefer this over ns1_get_zone or ns1_search, so the selection guidance is incomplete.

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, and destructiveHint=false, so safety is covered. The description adds genuine behavioral detail beyond that: matching is substring-based, and 'expand' governs whether record answers are included. It still omits result-cap/pagination behavior and what happens when nothing matches.

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 plus a bare endpoint reference, front-loaded with the search scope and with zero redundant phrasing. Every clause carries information the agent needs.

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 search endpoint with fully documented parameters and annotations covering the safety profile, the description covers purpose, matching semantics, and the expand effect. Only minor gaps remain (result limits/pagination and empty-result behavior), which the schema's max parameter partly addresses.

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 max, type, query, and expand with constraints. The description reinforces the substring nature of query and the effect of expand, but adds no syntax or format detail the schema lacks, making the baseline 3 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?

State a specific verb+resource ('Search the account's zones and records') with scope ('by name (substring match)') that separates it from ns1_get_zone/ns1_list_zones, which retrieve rather than search. It does not name any sibling explicitly, so an agent must infer the search-vs-get/list 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?

Usage is implied: reach for this when you want to locate zones or records by partial name instead of fetching them individually or listing everything. There is no explicit when/when-not statement and no mention of the sibling alternatives (ns1_list_zones, ns1_get_record), leaving the routing 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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description still adds high-value semantics the hints cannot convey: supplying answers REPLACES the entire answer set rather than merging, ttl-only input changes just the TTL, and filtered/steered records are refused. Return behavior and any auth/permission requirements are not described.

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 'WRITE:' prefix and the immediate live-DNS warning are correctly front-loaded, and every clause carries decision-relevant information. Slight redundancy remains in spelling out the plain-record type list, which duplicates the schema enum, and the paragraph packs several distinct rules into one dense block.

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 write with no output schema, the description covers existence preconditions, replacement semantics, unsupported-record refusals, and the endpoint. The main residual gap is what the call returns on success or failure, which the agent must infer since no output schema documents it.

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, and the description earns above it by explaining the operational meaning of 'answers' (complete replacement set, not a patch) and the ttl-only branch. It adds interpretation beyond the schema's field-level descriptions without restating them.

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?

Opens with a specific verb and resource scoped precisely: 'changes ONE existing DNS record' with the immediate live-DNS consequence stated up front. It implicitly separates itself from ns1_create_record by declaring 'Fails if the record does not exist', so an agent can tell update apart from create without reading 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?

Explicit when-not guidance is present on two axes: records that do not yet exist (route to create), and records using traffic-steering filters, links or per-answer metadata, which are refused here and must be edited in the NS1 portal instead. It also states the answer-vs-TTL branch that selects between two distinct update modes.

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