Suped DMARC

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

Goes well beyond the annotations: it discloses the auth requirement (regular org membership, not billing-only), the create-or-return-existing semantics, the archived-domain restore path, and the fact that no DNS records are touched. The annotations only declare readOnly=false, idempotent=true, destructive=false; the description supplies the operational detail that makes those hints actionable.

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 carrying distinct information (action, permission requirement, idempotent/restore behavior, non-effect on DNS). The clause "This adds the domain to Suped" is mildly redundant with the opening sentence, keeping it from a 5.

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 only two required params, the description covers the essentials: what happens on success, what happens if the domain exists, and the permission model. It does not describe the returned domain object's shape or any normalization behavior, a minor 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?

Schema coverage is 50%: 'domain' is documented in the schema, while 'organizationId' only carries a 24-hex pattern with no explanation. The description references "the specified Suped organization" but adds no guidance on how to source or format that ID, so it neither compensates for nor worsens the gap.

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 opens with a specific verb and resource ("Adds a domain to the specified Suped organization") and explicitly bounds the effect ("does not change the domain's DNS records"), which cleanly separates it from siblings like get_domains and get_dmarc_records.

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 a real precondition — regular organization access, with billing-only membership insufficient — which tells the agent when the call will fail. It stops short of explicitly routing between siblings (e.g., when to use this vs. get_domains), so it is clear context but not full 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=false, idempotentHint=false, and destructiveHint=false. Beyond that, the description adds the admin-only visibility constraint and explicitly warns that every successful call creates a new organization, which reinforces the non-idempotent behavior with concrete consequence. It doesn't discuss duplicate-name handling or failure modes, keeping it below 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?

Four short sentences, front-loaded with the action, then access constraint, then return shape. The final sentence slightly overlaps idempotentHint=false but earns its place by stating the side effect plainly.

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

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

For a two-parameter mutation with no output schema, the description covers access requirements, parameter sourcing, return shape, and the create-on-every-call side effect. Only duplicate-name or conflict behavior is 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%, so both parameters are already documented, including the pattern and the list_organizations hint. The description restates 'its organization ID, and a client name' without adding format or sourcing 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?

States a specific verb and resource — 'Creates a client organization under an existing MSP' — which an agent can easily separate from create_domain and list_organizations. It never explicitly contrasts itself with those siblings, so it falls short of a 5.

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

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

The description gives real prerequisites (administrator access to the parent MSP, organization ID, client name) and notes it is only advertised to MSP admins. However, it offers no when-to-use or when-not-to-use guidance relative to alternatives, so usage is only implied.

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

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

Annotations already cover the read-only, non-destructive profile, but the description adds genuinely new behavior: the return is raw XML served as an embedded application/xml resource, plus a non-obvious authorization rule that billing-only membership is insufficient. Missing detail on size limits or failure modes for very large reports.

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 what is returned before the access constraints. No filler or restatement 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?

No output schema exists, and the description does the needed work by describing the return payload format. Combined with the authorization caveat, an agent has enough to invoke correctly; only edge-case behavior (large reports, retention) 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 coverage is 50%: reportId is documented in the schema as coming from get_dmarc_records, while organizationId has no schema description. The description partially compensates by constraining organizationId (report must belong to it, regular access required), 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 concrete verb and resource: 'Returns the original raw XML for the specified DMARC report as an embedded application/xml resource.' The emphasis on raw XML implicitly separates it from the aggregate/record listing at get_dmarc_records, though no sibling is named explicitly.

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?

Explains prerequisites ('must belong to the specified organization', 'requires regular access... billing-only membership is insufficient') but never states when to pick this over get_dmarc_records or other siblings. Usage is implied by the prerequisites rather than given as routing 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 and destructiveHint=false, and the description adds genuinely useful context beyond them: the exact response envelope, the reportId field added per row, and the authorization prerequisite. It omits pagination/limits and result-size behavior for a potentially large record 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?

Three tight sentences, front-loaded with purpose then contract then prerequisites; each sentence carries information. Slightly dense with API-mirroring detail, but 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?

Complete enough for a 3-required-param read tool: it documents the return shape (no output schema exists), the filtering semantics, and the access requirement. Only edge behaviors like empty ranges or large result handling are 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 coverage is 67%, and the description compensates by explaining that startDate/endDate filter on reported end date inclusively and that endDate must not precede startDate — semantics absent from the schema. organizationId's 24-hex pattern is only conveyed via the schema, not the description.

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 ('Retrieves DMARC data') scoped to a Suped organization, and clarifies the return payload shape. It does not explicitly distinguish itself from the sibling download_dmarc_report, leaving the read-vs-download distinction to inference.

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 usage context: dates select reports by reported end date inclusively, endDate must be >= startDate, and regular organization access is required (billing-only insufficient). It stops short of naming when to prefer download_dmarc_report over this tool.

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/destructive=false and openWorld=false; the description goes beyond them by disclosing the return shape ({domain, archived}), that archived domains are included, and the authorization requirement. Pagination, ordering, and rate limits remain unspecified.

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 purpose, then return shape, then access caveat. No redundant or filler text.

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 helpfully documents the return array and the archived-domain inclusion, plus the access requirement. It is essentially complete for a simple list tool; only parameter format details are left to the 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 0%, so the single organizationId parameter is undocumented in structured fields. The description conveys that the parameter selects the Suped organization whose domains are returned and that billing-only memberships are rejected, but it omits format details (24-char hex ObjectId) and that the value is required.

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 ('Lists all domains') scoped to a named organization, which cleanly separates it from create_domain, list_organizations, and the DMARC tools. It stops short of explicitly naming a sibling or spelling out when listing domains is the right call versus another lookup.

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 resource and scope, and it adds a real prerequisite ('requires regular organization access; billing-only membership is insufficient'). However, it names no alternatives and gives no when-not guidance (e.g. when to use get_dmarc_records instead).

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=false and destructiveHint=false, so safety is covered; the description adds genuinely new context by disclosing that dismissed/resolved issues are included (not just open ones) and by spelling out the authorization tier required. It omits volume/pagination behavior, which keeps it out of the top band.

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, zero filler, and the core action is front-loaded ahead of the status scope and the access caveat. Nothing repeats the title or annotations.

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

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

For a single-parameter read tool with no output schema, the description covers action, scope, status breadth, and authorization. The only real gap is the identifier format and result size, both of which an agent would benefit from knowing before calling.

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 a single parameter at 0% schema description coverage, the description carries the burden and only says 'the specified Suped organization' — it does not explain that organizationId is a 24-character hex ObjectId or how to obtain one. The meaning is inferable but not enriched beyond 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?

States a specific verb and resource ('Lists all saved email authentication issues') plus the scoping dimension (per organization) and the breadth of statuses covered. It is clearly distinct from the sibling tools (create_domain, get_dmarc_records, list_organizations), though it never names an alternative, so it stops short of the top band.

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

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

The description gives a real prerequisite ('requires regular organization access; billing-only membership is insufficient'), which tells the agent when the call will fail. It does not, however, say when to prefer this over get_dmarc_records or any other sibling, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the result envelope and per-organization fields (id, name, isMsp, mspOrganizationId), which matters because no output schema exists. It says nothing about pagination or empty-list behavior, but with zero parameters a fully-returned list is a reasonable inference.

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 waste, and the scope constraint is front-loaded ahead of the return shape. The inline field list is compact enough not to 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?

A zero-parameter, read-only list tool with no output schema: the description supplies the missing return contract itself, plus the account scoping that determines what the list contains. Nothing an agent needs in order to call it 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?

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No false parameter hints are introduced.

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 pairs a specific verb (Lists) with a specific resource (organizations) and bounds the scope to those accessible to the connected Suped account, including MSP client orgs. It also enumerates the returned fields, so an agent knows exactly what it gets. It does not explicitly contrast with siblings like create_organization or get_domains, so it stops short of 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: an agent infers this is the discovery step before creating or querying domains. There is no explicit when-to-use statement, no exclusion clause, and no named alternative — though the 'accessible to the connected account' scoping does help an agent decide whether this covers MSP client tenants.

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