agent-health

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

Annotations already declare readOnly=false and destructive=false; the description adds useful non-annotation context: challenges expire in 24 hours, owner key is required, and the returned value must be published in DNS before verification. This enriches agent understanding without contradicting 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?

Three short sentences each carry distinct information: purpose, required workflow, and expiration behavior. The most important action is front-loaded and there is 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?

The tool has an output schema and only two parameters, so the description covers the high-level flow and expiry constraint. It is incomplete only in parameter semantics, and it does not explain what 'exact endpoint hostname' or the owner-key check entails, so a capable agent still needs to infer some details.

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

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

Schema description coverage is 0%, so the description must explain what agent_id and api_key mean. It only mentions 'Owner key required' and gives no guidance on where these values come from or how they relate to the challenge endpoint, leaving the agent to guess from parameter names.

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 action ('Issue/retrieve') and a clear resource ('DNS TXT challenge for your agent's exact endpoint hostname'), which distinguishes it from siblings like verify_agent_domain and agent_webhook_secret. It clearly communicates the tool's role in the domain-verification workflow.

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 the required prerequisite ('Owner key required') and the follow-up step ('call verify_agent_domain'), giving concrete context for when to use this tool. It does not explicitly enumerate exclusions or alternative tools, but the workflow instruction is specific enough for most agents.

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 indicate read/write openness, and the description adds concrete behavioral context: it performs two bounded HEAD/GET checks, operates on a DNS-verified endpoint, enforces a per-hour rate limit, and reports no score effect. The main unstated aspect is what happens if no previous assessment exists when consent=false, but this is minor given the output schema exists.

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

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

The description is brief, front-loaded, and every sentence carries meaningful information. It covers both consent modes, the rate limit, the operational scope, and explicitly disclaims audit/LLM-test functionality in two compact 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?

The description covers the essential behavioral modes, constraints, and exclusions, and an output schema exists to describe return values. However, it does not explain how agent_id and api_key are used or direct the agent to any alternative sibling tools when this tool is inappropriate. These gaps are moderate but not disabling.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains the consent parameter's true/false behavior, but agent_id and api_key are left completely unexplained. Their purpose may be inferable from names, but the description does not connect them to the DNS-verified endpoint or authentication context.

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 a specific verb and resource: "run two bounded HEAD/GET checks on your DNS-verified endpoint" or "read your last private result." It also distinguishes itself from audit/LLM tests by stating "Not an audit or LLM test; no score effect," which prevents confusion with similar assessment 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 explicit conditional usage based on consent: consent=true triggers checks, consent=false reads the last result. It also provides a rate limit ("max once/hour") and clarifies that this tool has no scoring effect. It doesn't name alternative sibling tools, but the mode-based guidance is clear enough for an agent to decide when to invoke it.

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 the description is not required to restate safety. It adds context by specifying that results are recent, HTTP/TLS-oriented, and limited to 1–500, which is useful. However, it does not disclose what 'recent' means, how results are ordered, or any pagination behavior beyond the limit.

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

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

The description is only two short sentences. The action and purpose come first, and the limit detail is front-loaded efficiently. There is no filler, redundancy, or unnecessary elaboration.

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?

The presence of an output schema and safety annotations reduces the burden on the description. Still, the description omits guidance for choosing this tool among several health-related siblings and fails to document the required agent_id. It is adequate for a straightforward read operation but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds meaning to the limit parameter ('Limit 1–500') and leaves the required agent_id parameter completely unaddressed. This is insufficient for a 2-parameter tool with zero schema-level documentation.

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 clear action ('Read'), a specific resource ('recent HTTP/TLS results'), and a purpose ('to diagnose failures'). This is more specific than a tautology and gives the agent a concrete idea of what the tool does, though it does not explicitly distinguish it from siblings like agent_health_status or agent_health_heartbeat.

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 'to diagnose failures' implies a use case, but the description does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions. With multiple health-related sibling tools, an agent could still be unsure whether to pick this over agent_health_status or agent_health_heartbeat.

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=false and destructiveHint=false. The description adds meaningful behavioral context beyond that: the auth requirement ('owner-authenticated', 'Use the agent-specific key, not X-Autonet-Token') and a misuse boundary. It stops short of describing what server-side state the heartbeat updates, but the added context is genuinely useful.

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

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

Three sentences, each earning its place: primary action and scope, auth key selection, and a misuse warning. The core purpose is front-loaded, with no filler or repetition of schema/annotation content.

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 2-parameter tool with an output schema present, the description covers purpose, usage context, auth specifics, and exclusions. The only gap is the unspecified server-side effect of a heartbeat on agent health state, which is minor given the output schema and annotations already carry the remaining burden.

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

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

Schema description coverage is 0%, so the description must compensate. It does so for api_key with the critical clarification 'Use the agent-specific key, not X-Autonet-Token', which prevents a common auth mistake. The agent_id parameter, however, is left only to the schema title 'Agent Id' with no additional guidance on format or source.

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: 'Send an owner-authenticated heartbeat from the actual worker loop'. The explicit exclusion 'does not replace endpoint checks' differentiates it from sibling tools like agent_health_checks and agent_endpoint_assessment. An agent can tell what this tool is for 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?

Gives an explicit when ('from the actual worker loop') and explicit when-nots ('does not replace endpoint checks', 'Never send a heartbeat to pretend a failed worker is alive'). It also provides a routing hint by distinguishing heartbeat signaling from endpoint checks, which are presumably handled by sibling tools.

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 the safety profile is well established. The description adds useful context about the contents and scope of the instructions, giving the agent expectation about what information will be provided without contradicting 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?

The description is a single, front-loaded sentence that begins with the critical directive 'Read FIRST' and then lists the covered topics in a compact, scannable format. Every phrase earns its place and there is no filler.

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

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

For a parameterless instructions tool with output schema available and annotations covering safety, the description is complete. It tells the agent exactly what content to expect (purpose, endpoint ownership, heartbeat setup, scoring limits, API usage) and signals where this fits in the overall workflow.

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 has zero parameters, so the input schema carries no burden and the description needs to explain nothing extra. The baseline for a parameterless tool is 4, and the description appropriately focuses on the tool's content rather than parameters.

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

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

The description clearly identifies this as a 'read first' instructions tool, listing the specific topics it covers: purpose, endpoint ownership, heartbeat setup, scoring limits, and API/free service usage. This distinguishes it from the sibling tools that perform actual health operations, though it stops short of explicitly stating 'returns onboarding instructions'.

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?

'Read FIRST' is an explicit temporal cue that this tool should be used before the other agent health tools. It conveys the intended ordering and scope of use, though it does not directly name sibling alternatives or explicitly say 'use this before agent_health_checks'.

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 convey readOnly/openWorld/non-destructive. The description adds context by noting the status is public, the trust score is nested, may be null ('Provisional score is null'), and the result is not a certification. This exceeds the annotation baseline without contradicting it.

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 compact sentences, with the primary operation front-loaded and the caveat packaged efficiently. There is no filler or repetition.

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

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

For a simple single-parameter read tool with an output schema and safety annotations, the description covers the essential behavior: public status, trust score, nullability, and what it is not. It could add one sentence on typical use, but nothing critical 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 0% and the description does not explain agent_id or how to obtain/use it. The parameter name and schema title make it obvious, but the description itself adds no semantic value for the only required parameter.

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

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

Description specifies a clear verb and resource: 'Read public operational status and nested trust score.' It also adds a distinguishing negative ('not identity/safety certification'), though it does not explicitly differentiate from sibling health/check 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 phrase 'read public operational status' implies a lightweight read-only status lookup, and 'not identity/safety certification' offers an exclusion. However, it gives no explicit guidance on when to prefer this over agent_health_checks or agent_health_heartbeat.

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 indicate the operation is non-read-only and non-destructive, but the description adds the authorization boundary ('Owner-only'), the rotation policy ('when explicitly requested'), and a security handling rule ('Keep the secret private'). This is meaningful behavioral context beyond the annotation flags, though rotation side effects are not detailed.

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

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

The description is only two short sentences with no filler. It front-loads the primary action and each clause adds necessary context about scope, behavior, or confidentiality.

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

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

With an output schema present and only three scalar parameters, the description covers owner-only access, the retrieve/rotate operations, and secret sensitivity. However, it does not clarify the required parameters or the effects of rotation, leaving a moderate completeness 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 description coverage is 0%, and the description does not explicitly explain agent_id, api_key, or rotate. The phrase 'when explicitly requested' only loosely hints at the rotate parameter, leaving the meaning of the other parameters to be inferred from their names.

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

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

The description uses specific verbs, 'retrieve' and 'rotate', with a clear resource, 'webhook signing secret', and an explicit owner-only scope. It is easy to distinguish from sibling health/domain tools because the resource and operation are different.

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 clearly states the two relevant use cases: retrieving the secret or rotating it only when explicitly requested. It also provides the owner-only restriction and a privacy directive, though it does not explicitly name alternatives or when not to use 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 mark the tool as destructive, and the description adds valuable specifics: it permanently removes both the registration and probe history, and admin request logs are retained for up to 30 days. This goes beyond the annotations by clarifying the exact scope and retention behavior.

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

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

Two sentences with no unnecessary filler. The most important information—permanent deletion and retention of admin logs—is front-loaded and clearly stated.

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 tool with an output schema, the description covers the essential details: what is deleted, permanence, and log retention. It does not mention error cases or idempotency, but the presence of an output schema and the clarity of the operation make this a reasonably complete description.

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

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

Schema description coverage is 0%, so the description bears the burden of explaining parameters. It refers to 'owned registration' and 'operator', which hints at authorization, but it never explicitly defines what agent_id or api_key mean or how they are used. The parameter names are somewhat self-explanatory, but the description does not compensate for the missing schema descriptions.

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 action: 'Permanently remove an owned registration and probe history' with a specific verb and resource. It is easily distinguished from sibling tools like register_agent_health, update_agent_health, and agent_health_status.

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 'when the operator requests it' gives clear context for when deletion is appropriate. It does not explicitly contrast with sibling tools, but the delete-vs-register/update/status distinction is clear from the description and tool name.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses that a returned api_key must be saved securely, that name/endpoint/history are public, that the endpoint should be a cheap GET returning 2xx only when ready, and that intervals must be 30–3600 seconds. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

The description is compact yet dense with actionable detail, with the core purpose front-loaded in the first sentence. Every sentence contributes a meaningful registration constraint or clarification.

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?

The description is effectively complete for a registration tool: prerequisites, endpoint requirements, privacy warnings, interval bounds, and heartbeat conditions are all covered. The presence of an output schema means the return value does not need detailed explanation.

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 0% schema description coverage, the description compensates well. endpoint_url is explained as requiring a public, cheap GET endpoint; check_interval_sec gets an explicit range; heartbeat_enabled gets a clear condition; even name is given privacy-relevant meaning by noting it is public.

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 action: register once your own deployed public agent readiness endpoint. It names the specific resource type and distinguishes the operation from sibling tools like agent_health_heartbeat and update_agent_health by emphasizing one-time registration and readiness-endpoint semantics.

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 explicit when-to-use and when-not-to-use guidance: read agent_health_instructions first, never register example.com/vendor pages, do not register without a public endpoint, and heartbeat-only monitoring is unsupported. It also tells the agent to enable heartbeats only when automatic sending is guaranteed.

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 is a non-read, destructive operation, so the description is not required to repeat that. It adds useful behavioral context beyond annotations by stating the operation is owner-only, explaining pause/resume semantics, and requiring public URLs under the caller's control. This helps an agent understand permissions and deployment constraints that 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?

The description is three tight sentences with no filler. The most important constraint ('Owner-only update') is front-loaded, and each sentence adds operational value: ownership, pause/resume usage, and URL requirements. It is an ideal size for the tool's complexity.

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

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

Given seven parameters, an output schema, and destructive annotations, the description covers the main update scenarios but leaves heartbeat-related parameters unexplained and does not state whether unspecified fields are preserved or reset. The output schema and annotations reduce the burden, but an agent still lacks enough context to confidently use all optional fields.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully clarifies paused, endpoint_url, and webhook_url, including the public-URL requirement and pause/resume behavior. However, it does not address heartbeat_enabled or check_interval_sec, leaving the agent to infer those from parameter names alone, so coverage is incomplete but not absent.

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 an owner-only update operation on agent health, and gives concrete examples of what can be changed: pause/resume and endpoint/webhook URLs. It does not explicitly say 'update agent health configuration', but the name plus these examples make the resource and action clear enough to distinguish from tools like register_agent_health or delete_agent_health.

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 clear context for when to use the update: pause when retiring/testing and resume with paused=false. It also gives a critical precondition: endpoint and webhook must be public URLs you control. It does not mention alternatives or explicit when-not-to-use cases, but the owner-only and update-specific instructions are sufficient for most selection decisions.

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 only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral details beyond annotations: the once-per-minute check limit, hourly renewal on success, and 24-hour expiry. This gives the agent a realistic model of side effects and limitations without contradicting 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?

Three short sentences carry essential information: the action, the limitation, and the lifecycle behavior. There is no filler or repetition, and the most important scoping statement 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?

The description covers the verification lifecycle well and an output schema exists, so return-value documentation is not needed. However, it omits the prerequisite relationship with agent_domain_challenge, and it never explains which domain the TXT record should be on or how agent_id and api_key map to that domain. This leaves gaps for an agent deciding whether it has everything needed.

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 two required parameters, agent_id and api_key, with 0% schema description coverage. The description says nothing about what either parameter means, which domain is verified, or how the API key is used. The schema only provides titles, so the agent must guess crucial invocation 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 uses a specific verb and resource ('Check your published DNS TXT record') and immediately clarifies the scope ('Proves domain control only, not agent identity or safety'), distinguishing it from identity or safety verification tools. The purpose is unmistakable.

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 implies usage: check a DNS TXT record after publishing it, and use it when domain control proof is sufficient. It does not explicitly state when to prefer this tool over siblings like agent_domain_challenge, nor does it give an explicit when-not-to-use condition, though the 'not agent identity or safety' caveat provides useful context.

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