AI SENSE Free Public Tools

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

Beyond the annotations, the description reveals meaningful behavioral details: repeated acknowledgement with the same winning receipt succeeds, different or stale receipts conflict, and completion does not reclaim the lifetime job allowance. This adds value beyond idempotentHint and destructiveHint and does not contradict any annotation.

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 with no filler. The core action is stated first, followed by idempotency and conflict behavior, then the allowance consequence. Every sentence contributes useful information.

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

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

Given the presence of an output schema, annotations, and a clear description covering purpose, prerequisites, idempotency, conflict behavior, and a key side-effect, the definition is complete enough for an agent to invoke the tool 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 0%, so the description must carry semantic weight. It explains the role of the worker token and the receipt, including what makes a receipt valid or conflicting. The queue_id and job_id parameters are not explicitly described, but their names and schemas make them reasonably self-explanatory.

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: 'Mark a claimed job completed using the worker token and its current receipt.' This clearly identifies the operation and distinguishes it from sibling tools like claim_agent_queue_job, release_agent_queue_job, and renew_agent_queue_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 description gives clear context: use this when a claimed job is completed, with the worker token and current receipt. It also explains important usage conditions around repeating the same receipt versus a stale or different receipt, but it does not explicitly name alternative tools for non-completion actions like release or renew.

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 are sparse (no idempotency flags), and the description compensates by disclosing the success result (owner + monotonic fencing token), the possible outcomes for later callers, and the fact that contention is normal. 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?

Four short sentences, front-loaded with the core purpose, followed by outcome/contention guidance and namespace advice. Every sentence 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?

Description covers purpose, outcomes, contention expectations, key safety, and authentication. Return-value details are already handled by the output schema, so nothing needed for a correct invocation 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 applies; the description's namespace/key advice mainly restates the schema's guidance rather than adding new per-parameter semantics. No additional value is added for fingerprint or ttl_seconds beyond what the schema already 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?

States a concrete verb ('Claim') and resource ('one unit of work'), explains the concurrency goal, and is instantly distinguishable from sibling lease tools (release_lease, renew_lease) by describing acquisition behavior rather than lifecycle operations.

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

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

Provides clear usage context: use when work must not be executed twice concurrently, and advises key/namespace strategy ('Use a private namespace, or supply a high-entropy unscoped key'). It does not explicitly name alternatives or exclusions, but the context is strong enough for selection.

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 provide no useful safety hints (all false), so the description carries the full burden. It discloses immediate null return, secret receipt issuance, visibility timeout range, redelivery semantics, the 5-claim failure limit, and the fact that no job executes server-side—far more than the structured fields alone 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 front-loaded with the action and resource, and every subsequent sentence adds a distinct behavioral or safety fact. No filler is present.

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

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

The description is largely complete for invoking the tool: outputs (null vs. job with secret receipt), visibility constraints, failure limit, and redelivery caution are all covered. It falls just short of full completeness by not explaining queue_id or what an agent should do with the returned receipt (e.g., use it for subsequent ack/renew/release calls).

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?

Only visibility_timeout has schema documentation, so the low coverage requires compensation. The description does explain worker_token's role and visibility_timeout's range and default, but queue_id is never described beyond its schema pattern; it must be inferred from the tool name and parameter name.

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 ('Claim the next pending job') and clarifies it uses a worker token. It also distinguishes the operation from siblings by stating the server does not execute jobs and that a returned job contains a new secret receipt.

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 when to use it: when a worker wants the next pending job, and it warns that redelivery is possible so workers should make side effects idempotent. However, it never explicitly contrasts this with sibling operations like ack_agent_queue_job, release_agent_queue_job, or renew_agent_queue_job, so an agent must infer the appropriate choice.

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 behavioral details beyond the annotations: the 32 KB size limit, redaction of secret-shaped fields, a warning not to store secrets or personal data, and that no authentication is required. These are useful constraints not present in the annotations. It does not disclose post-completion state changes (e.g., lease consumption), but the annotations and output schema partially cover that.

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 concise, with the primary purpose stated first, followed by constraints and security notes. It is not overly verbose, though it is broken into multiple short sentences, which slightly fragments the flow. Overall, it is well-structured and front-loaded with the core action.

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

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

Given the tool's complexity (lease lifecycle, multiple parameters, output schema present) and minimal annotations, the description covers key operational constraints: size limit, redaction, storage guidance, and auth requirements. It lacks an explicit note on the lease's terminal state or error conditions, but the output schema and sibling context mitigate this. It is sufficiently complete for correct invocation.

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

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

The input schema provides detailed descriptions for all four parameters (100% coverage), including format and constraints for key, owner_token, namespace, and result. The description adds no additional parameter-specific meaning; it only mentions the owner token requirement, which is already in the schema. Thus, the description does not enhance beyond schema coverage.

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 ('Finish owned work') and resource (owned work with a lease), and explains the outcome (save a reusable JSON result for later callers with the same identity and fingerprint). This clearly distinguishes it from sibling lease operations like acquire_lease or release_lease by focusing on completion and storage.

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 for completing a lease after work is done, but it does not explicitly contrast with alternatives such as release_lease (abandoning) or renew_lease (extending). While the sibling names suggest context, the description lacks explicit 'when to use' or 'when not to use' guidance, so an agent must infer the appropriate choice.

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

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

Beyond the annotations, the description discloses crucial non-obvious behavior: the address is public by construction, the inbox_id is the sole secret credential, read_url and wait_url are equally secret, mail is untrusted, storage caps at 20 messages and 256 KiB, and no API key is required. This deeply informs any agent calling the tool.

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

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

The description is longer than most, but every sentence earns its place by supplying a distinct operational or security fact. It is front-loaded with the core purpose and then systematically covers credentials, reading, storage caps, and trust assumptions without 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?

For a stateless creation endpoint with no parameters, the description is fully complete: lifetime, public/private credential split, correct read path, message and size caps, untrusted content warning, and lack of authentication. Nothing an agent needs to safely invoke or reason about the result 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?

The tool has zero input parameters and the schema coverage is 100%, so there is no parameter documentation burden. The description adds useful meaning around the returned identifiers (they are not interchangeable, one is public, one is secret), but this is output semantics rather than parameter semantics, so the baseline 4 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?

Description opens with a specific action verb 'Create' plus the resource 'private email inbox' and states its 24-hour lifetime and purpose. It clearly distinguishes itself from sibling tools such as create_webhook_capture and read_agent_inbox by naming the exact artifact and use case.

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 gives strong when-to-use context: an agent needs to receive a confirmation mail, verification code, or one-time link while it works. It also explicitly directs reading to read_agent_inbox and warns against using the address or slug. It does not enumerate when-not cases for other creation tools, but the resource difference is obvious.

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 is exceptionally transparent about behavioral details beyond annotations: the fixed 24-hour non-extendable lifetime, single issuance of read/write/worker bearer tokens, secret-sharing guidance, job and payload limits, claim limits, per-IP queue limits, non-execution of jobs, and lack of account/API key requirements. This fully compensates for the sparse 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 front-loaded with the core purpose and then efficiently packs the most decision-relevant constraints, token handling, quotas, and execution semantics. No sentence is filler; each adds operational guidance an agent would need.

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 zero-parameter creation tool with an output schema available, the description is remarkably complete. It covers lifetime, authentication tokens, secrets, rate and size limits, non-execution behavior, and authentication requirements, leaving an agent with enough context to invoke the tool correctly.

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

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

The input schema has zero parameters, so parameter semantics carry little burden. Baseline for zero-parameter tools is 4, and the description appropriately focuses on behavioral and usage context instead of parameter syntax.

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: 'Create a small temporary pull queue for cooperating agents.' It clearly identifies this as a queue-creation tool, distinct in nature from sibling inbox, wake, webhook, and heartbeat tools, and it does so without simply restating the tool name.

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 clear context for when this tool is appropriate: creating a temporary pull queue for cooperating agents. It also states that the server does not execute jobs, helping an agent understand this is not a job-execution tool. It does not explicitly name alternative tools or give direct when-not-to-use guidance, but the context is strong enough.

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 indicate readOnly=false, openWorldHint=true, idempotent=false, and destructive=false. The description adds valuable behavioral context beyond those: bodies and human answers are readable by anyone with the task URL, secrets should not be sent, and task lifetime ranges from 60 seconds to 24 hours. Nothing in the description contradicts 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 compact and front-loaded: it defines what the tool does, specifies when to use it, states the duration limit, and includes an important security caveat. Every sentence contributes useful information with no redundancy or 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 input schema and output schema already cover parameter and return details, so the description can focus on lifecycle, security, and intent, which it does. It adequately covers the usage scenario and important caveats, though it could have named sibling tools like create_human_approval or create_webhook_capture to further guide selection.

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 each parameter already has a clear description in the schema. The tool description adds no additional parameter-level meaning beyond grouping the event types, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: creating a durable MCP task that completes on a webhook, form answer, or time event. It is specific about the resource and behavior, and the three event types make it easy to distinguish from the read-focused sibling tools. It does not explicitly name the overlapping create_human_approval or create_webhook_capture tools, so it slightly misses the chance to differentiate itself from them.

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 explicit guidance: "Use it when an agent must pause and continue after an outside event without holding one HTTP request open." This gives a clear usage context. It does not describe when not to use it or refer directly to sibling alternatives, but the stated condition is actionable.

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

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

Beyond the sparse boolean annotations, the description discloses the one-time dns_token, 24-hour expiry, inability to extend, fact that the name is assigned rather than chosen, and the PSL/certificate-sharing caveat. These are exactly the non-obvious behaviors an agent needs to avoid misusing the tool.

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

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

The definition starts with the core action and duration, then follows with use cases and constraints in a logical order. Every sentence adds a distinct, load-bearing fact; none repeat the schema or annotation data.

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-shot ephemeral naming tool, the description covers lifecycle, output characteristics, security implications, and boundary conditions ('without it the name cannot be changed or removed'). An agent has enough context to call it directly and interpret the result even before seeing the output schema.

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

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

The input schema already covers both parameters with descriptions, so the baseline applies; the description adds usage context rather than new parameter syntax. Its 'address you already control' phrasing reinforces the required ip field but does not change the mechanics documented in 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?

The description names a specific verb and resource ('Point a public hostname at an address') with a clear temporal scope ('for 24 hours'), making the tool's core function unmistakable. It also distinguishes this from the sibling read/update/delete DNS tools by describing a fixed one-shot, auto-expiring naming service.

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 use cases ('a webhook target someone has to type, a staging box whose address moves') and tells the agent what it is not for ('no tunnel, no hosting, no certificate and no HTTPS'). It does not name sibling tools as alternatives, but the when-to-use guidance is strong enough to route correctly.

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 this is a write operation (readOnlyHint=false, destructiveHint=false). The description adds valuable behavioral context: the monitor lasts at most 24 hours, pings cannot extend that limit, and the returned heartbeat ID and URLs are bearer secrets. It also explains the miss action (webhook or wake task). This goes beyond the annotations and helps the agent understand side effects and security implications.

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 concise and front-loaded with the core purpose. It covers the key behavioral constraints (24-hour limit, bearer secrets, no auth required) in a compact, well-structured paragraph. Every sentence adds value, and the structure flows logically from purpose to usage to constraints.

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

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

Given the tool's complexity (nested on_miss object, two mutually exclusive target types, time constraints) and the presence of an output schema, the description is complete. It explains the miss action, the time limits, the security model, and the relationship between parameters. An agent has enough information to call this tool correctly without additional context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context by explaining the relationship between expect_every_seconds and grace_seconds ('The expected interval plus grace must not exceed 86400 seconds') and by clarifying the on_miss target options ('Use url for a public HTTP or HTTPS webhook on port 80 or 443, or wake_task_id for an active Agent Wake webhook task'). This adds meaning beyond the raw 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?

The description clearly states the tool's purpose: 'Create a deadline monitor for a job, device or agent that should keep checking in.' It uses a specific verb ('create') and resource ('deadline monitor'), and distinguishes it from siblings like ping_heartbeat and read_heartbeat by explaining the creation role and the monitoring behavior.

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 explicitly tells the agent when to use this tool: 'Call ping_heartbeat before the expected interval plus grace period ends.' It also explains the miss behavior and the 24-hour limit, which clarifies when this monitor is appropriate. It doesn't explicitly name alternatives, but the context of creating a monitor versus pinging it is clear.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description goes well beyond that by disclosing key behaviors: forms expire after 24 hours, no auth is required, notify_url fires only after the final answer and does not include answers, group results contain counts/tally/anonymous responses, and each form link can answer once. This is exactly the behavioral context an agent needs to set expectations correctly.

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 paragraph with no wasted words, and it front-loads the most important fact: who the decision goes to and the one-vs-many distinction. It is compact but dense; it could earn a 5 if it added one explicit 'Use this when...' clause, but it is still efficiently structured.

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 that an output schema exists, a 6-parameter input schema is fully documented, and annotations cover safety profile, the description covers all the behavioral gaps an agent might worry about: auth, expiry, callback content, anonymous group responses, and response limits. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds a bit of context around notify_url (one small signal, no answers) and around respondents (separate form links), but most parameter meaning is already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific, concrete verb phrase ('Put a decision in front of one to twenty people') and differentiates the tool from the sibling read_human_approval and other create_* tools by explaining exactly what it produces: human approval forms. It clearly names the resource (human approval) and the action (create/request), so an agent can distinguish it from create_webhook_capture or create_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 description explicitly states when to use one respondent vs several ('Use one respondent for a normal approval, or several when every invited person should answer through a separate bearer form link') and mentions the forms' 24-hour expiry and the no-API-key requirement. It doesn't explicitly name sibling alternatives to avoid, but the usage context is clear enough for an agent to know when this is the right 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?

Beyond the annotations, the description reveals important behavioral traits: the namespace is a bearer secret, is returned only once, and must be shared only with cooperating agents. It also clarifies that no authentication is required and that the operation stores no lease, giving the agent useful safety and side-effect context well beyond the structured 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 compact and front-loaded with the core purpose, then adds secret-handling and side-effect information in short, purposeful sentences. Every sentence adds meaningful guidance without redundancy or 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 zero-parameter tool with an output schema, the description fully covers what the tool does, when to use it, how to handle the returned secret, authentication needs, and side-effect behavior. Nothing important is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters and the schema description coverage is 100%, so there are no parameter details needing clarification. The description adds context by noting no authentication is required, which is relevant to why no credential parameters exist. The baseline for zero-parameter tools is appropriate.

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

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

The description clearly states the verb 'Create' and the specific resource, a random private namespace, and explains its purpose: allowing several agents to coordinate work using short readable keys. It also distinguishes itself from lease-related siblings by noting it stores no lease, so an agent can tell it apart from acquire_lease and similar 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 a clear context for when to use the tool: before multi-agent coordination that relies on short readable keys. It does not explicitly name alternatives, but the distinction from lease tools is implied by 'stores no lease,' and the guidance to share the namespace only with cooperating agents makes appropriate usage clear.

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

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

Beyond the annotations, the description discloses important behaviors: the pending capture is stored before the call returns, the optional notify_url receives a completion signal only after the first request, that callback does not contain the captured request, and that anything sent to the generated URL becomes publicly readable. This is unusually transparent about timing, callback payload, and security/privacy implications.

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 dense but not bloated: it front-loads the main purpose, then gives usage rationale, setup simplicity, timing, callback semantics, and a privacy warning. Each sentence contributes, though the final sentence's 'update_url' wording could be tightened to avoid ambiguity with notify_url.

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 a single optional parameter, an output schema, and annotations, the description covers the essential behaviors needed to call the tool correctly: what it creates, what the capture captures, when it is persisted, how the callback behaves, and privacy limitations. Minor gaps like explicit expiration or a clearer name for the generated URL are not critical for correct invocation.

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

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

Schema coverage is 100% for notify_url, and the description adds meaning by explaining that it receives 'one small completion signal with a result URL after the first request arrives' and that it does not contain the captured request. The mention of 'update_url' is slightly confusing since that is not a declared parameter, but the single param is otherwise well explained.

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: 'Create a throwaway URL that records the next HTTP request anyone sends to it, headers and body included.' It also gives concrete use cases (inspecting webhook/form/third-party traffic, proving an integration fired), which clearly distinguishes it from read_webhook_capture and the other sibling 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 states explicit usage context: 'Use it to see what a webhook provider, a form or a third party service actually transmits, instead of trusting their documentation, and to prove that an integration fired at all.' It does not name alternatives or state when not to use it, but the intended scenario is clear enough that an agent can route correctly.

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 goes well beyond the annotations by disclosing the exact DNS propagation behavior: primary server removal is immediate, secondary servers follow via replication and may keep answering if disconnected, and resolvers retain cached answers up to 60 seconds. This is valuable operational context that annotation hints alone 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 concise, front-loaded with the core action, and every sentence contributes useful information about timing, prerequisites, or propagation behavior. There is no wasted wording or irrelevant detail.

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 operation with an existing output schema and rich annotations, the description covers purpose, timing, prerequisites, and observable side effects. An agent has enough information to decide when to call the tool and what to expect afterward, so no critical context 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?

With 100% schema description coverage, the schema already thoroughly documents both 'slug' and 'dns_token', so the description need not restate them. The description adds a small reminder that dns_token is required, but it does not materially enrich parameter semantics 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 action ('Remove a temporary DNS name now, before its 24 hours are up') and differentiates this from sibling tools by emphasizing immediate removal versus waiting for expiration. It is specific about the resource type and avoids simply restating the tool name.

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 clear when-to-use instruction ('Use it when the work is done and the name should stop answering') and mentions the required dns_token prerequisite. It does not explicitly name an alternative tool for scenarios where the name still needs to answer, but the guidance is sufficiently clear for the common delete use case.

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 signal idempotency, non-read-only, and non-destructive behavior. The description goes further by explaining the exact conflict rule, the 16 KiB payload limit, the no-secrets requirement, and the 100-job lifetime cap. No contradiction with annotations.

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

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

Four focused sentences, each adding a distinct constraint or behavior. The primary action is front-loaded, and there is no filler or redundant restatement.

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 idempotency, conflict behavior, payload constraints, security policy, and lifetime limits. With an output schema present, return-value documentation is unnecessary, and the remaining parameters are adequately covered by names and schema patterns.

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 only 25%, so the description must compensate. It adds meaning for job_key (stable, idempotency key) and payload (JSON, size limit, data sensitivity), and references write_token's role. However, queue_id and write_token semantics are mostly left to their names and regex patterns.

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 ('Add a JSON job') and clarifies the central idempotent behavior. It clearly differentiates this enqueue operation from sibling read/claim/release/renew operations through the stable job_key and conflict 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?

The intended use is implied: use this tool to add a job to a queue. However, the description does not explicitly compare against alternatives or state when not to use this tool, so the agent must infer routing from purpose and sibling names.

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 discloses that it returns a single lowercase hyphenated UUID and is random, and mentions the lack of authentication requirements. While the readOnlyHint annotation already indicates safety, the description adds useful behavioral details without contradicting the annotation.

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 slightly verbose but every sentence adds value—purpose, usage, output, and access details are all covered. It is well-structured with hyphens and dashes, making it readable without being overly long.

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

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

Given the tool's simplicity (no parameters, straightforward output), the description covers all necessary aspects: what it does, when to use it, what it returns, and authentication requirements. It is complete and self-contained.

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, and the description explicitly states 'Takes no parameters,' which aligns with the empty schema. Since there are no parameters to explain, the description sufficiently covers this aspect.

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 tool generates a random RFC 4122 version 4 UUID, with explicit use cases like idempotency keys and correlation IDs. It also distinguishes itself from inventing strings, making the purpose unambiguous.

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

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

It provides specific guidance on when to use (when a collision-free identifier is needed) and when not to (when inventing strings). The note about no API key or signup further clarifies its accessibility, though it doesn't explicitly contrast with 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 mark the tool as read-only and idempotent; the description adds valuable behavioral context on top: it is a true external-clock call, requires no API key or account, returns both ISO 8601 and Unix timestamp, and accepts IANA/offset timezones. It does not contradict 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?

Every sentence earns its place: purpose/output, usage guidance, auth/directness, and parameter semantics are each covered in a compact four-sentence structure with no filler. The key action is front-loaded in the first sentence.

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-optional-parameter tool with an output schema and safe annotations, the description is complete: it covers what, when, why, auth, and parameter behavior. The output schema handles return-value details, so the description need not repeat them.

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 schema already fully documents the timezone parameter with a default and example formats at 100% coverage. The description paraphrases that same meaning ('IANA name or a fixed UTC offset and defaults to UTC'), adding little value 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?

The description opens with a specific verb and resource ('Get the true current date and time') and names the concrete return forms (ISO 8601 string and Unix timestamp). It also scopes the tool to any timezone, clearly distinguishing it from unrelated sibling tools such as generate_uuid.

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 gives explicit when-to-use guidance ('whenever the actual present moment matters') with concrete examples like stamping records, computing ages/deadlines, and expiration checks. It also explains why an LLM should not guess the time, making the guidance actionable and unambiguous.

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 are all false and provide no behavioral protection, so the description carries the full burden. It discloses the side effect (moving the next expected deadline), a non-obvious limitation (does not extend absolute lifetime), and security context (heartbeat ID is a bearer secret; no authentication required). This is rich, accurate, and goes beyond the 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?

Four short sentences with no filler. The core action is first, usage follows, then critical caveats, then authentication. Every sentence earns its place.

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

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

With a single parameter, an existing output schema, and annotations that are all false, the description covers the essential operational facts: what the tool does, when to use it, the non-renewal caveat, and security handling. No crucial information appears to be missing for an agent to invoke 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%, so the baseline is 3. The description adds value by emphasizing the heartbeat_id is a 'bearer secret,' which strengthens the schema's 'secret heartbeat ID' by implying it must be protected like a credential. It does not add format details, but the schema already includes pattern.

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: 'Record a check-in for an armed heartbeat and move its next expected deadline.' It clearly distinguishes this from sibling tools like read_heartbeat (read-only) and create_heartbeat (creation), and the effect is concrete.

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 gives explicit when-to-use guidance: 'Use it after successful work or from a liveness loop.' It also states a key when-not-to-use caveat: 'A ping does not extend the absolute 24 hour lifetime.' However, it does not name alternative sibling tools for comparison, so it stops short of a perfect 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 declare readOnly and idempotent, and the description adds substantial behavioral detail: attachments and raw headers are not stored, 20-message and 256 KiB caps with truncation semantics, the reply uses a public slug and never repeats the secret inbox_id, unknown and wrong inbox_id fail identically while expired inboxes differ, and no API key or account is required. This covers safety, failure modes, and response nuances.

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?

Longer than average, but every sentence carries distinct operational information: content shape, omitted attachments/headers, wait behavior, normal empties, truncation consequences, identifier secrecy, failure indistinguishability, and lack of auth. It is front-loaded with purpose and contains 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 read tool with readOnly and idempotent annotations, an output schema, and full parameter schema coverage, the description supplies all missing behavioral context an agent needs: caps, truncation, empty semantics, failure modes, and identifier handling. Nothing essential is left unexplained.

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

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

Schema description coverage is 100%, so the schema already defines both parameters. The description adds value by clarifying wait_seconds behavior, the meaning of an empty result, truncation consequences, and inbox_id secrecy/failure behavior, going beyond the schema without needing to repeat field-level format 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 opens with 'Read the mail that has arrived in an inbox from create_agent_inbox', naming a specific verb and resource and referencing the creating sibling. It is clearly the agent-inbox reader, distinct from read_heartbeat, read_human_approval, read_webhook_capture, and read_temporary_data.

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 clear operational guidance: wait_seconds 0 returns immediately, 1 to 25 waits, an empty inbox is a normal pre-delivery result, and truncation means a message may have been refused. It doesn't explicitly contrast with sibling read tools, but the tool name and context make the domain unmistakable.

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 operation as readOnly, idempotent, and closed-world. The description adds meaningful behavior beyond this: it requires a read token, does not expose payloads or role tokens, and does not extend the fixed expiry. These are important non-obvious safety and lifecycle 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?

Two concise sentences front-load the primary purpose and then state the key exclusions. Every sentence adds value, and there is no redundant repetition of the tool name or 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?

Given the presence of an output schema, strong safety annotations, and only two simple parameters, the description is complete. It covers the operation's scope, its access-token requirement, and its non-actions, leaving no critical decision gap for an agent.

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 description must compensate. It clarifies that read_token is used as a scoped read credential and mentions security boundaries, but it does not explicitly define queue_id beyond the property name and tool context. The two parameters are simple and self-evident, but the description could do slightly more to document 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?

The description states a specific action ('Read queue metadata and pending, claimed, completed and failed counts') tied to a clear resource ('agent queue'). It also distinguishes the tool from siblings by explicitly stating what it does NOT do: list payloads, disclose role tokens, or extend the fixed expiry.

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 makes the context clear: use this tool for read-only queue-level metadata and counts with the read token. It also gives exclusions by stating it does not list payloads or disclose role tokens, though it does not name an explicit alternative sibling for those cases.

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 readOnly, idempotent, and non-open-world behavior. The description adds meaningful security context by stating that active claim receipt and role tokens are never returned, which is not captured by the annotations and is important for an agent to know.

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 concise sentences, with the primary operation front-loaded and a critical security caveat stated without extra words. 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 read-only tool with an output schema and annotations, the description covers the core behavior, token usage, and the sensitive fields excluded from responses. It does not address error scenarios or sibling selection explicitly, but those are secondary given the other structured signals.

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 clarifies that the read_token is used for read access and that the job is 'known' via queue_id and job_id, but it does not elaborate on formats, relationships, or edge cases.

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 operation: reading one known job, its JSON payload, and status using a read token. The qualifier 'known job' distinguishes it from listing or queue-level tools, though it does not explicitly name sibling alternatives.

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 context is implied: use this when you have a specific queue_id, job_id, and read token to inspect a single job. However, there is no explicit guidance about when not to use it or which sibling tools to prefer 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that no token is required, that all returned data is already public in DNS, and that the lookup fails once the name expires, including the exact timing of expiry. This is valuable behavioral context the annotations do not provide.

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 concise sentences, with the main purpose front-loaded and no filler. Each sentence adds relevant information: what it does, authentication implications, usage context, and failure behavior.

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-only tool with an output schema and comprehensive annotations, the description covers all the extra context an agent needs: purpose, usage, auth requirements, and expiry behavior. Nothing important 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?

The schema covers the only parameter, slug, with a clear description including the pattern, length, and the instruction to omit the prefix and zone. With 100% schema description coverage, the description does not need to add more, and it doesn't, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Look up') and resource ('temporary DNS name'), and specifies what it returns: the target and remaining lifetime. It is clearly distinguishable from sibling tools like create_dns_name, delete_dns_name, and update_dns_name.

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 provides clear use context: confirm a name exists and resolves as expected before handing it to someone else. It also notes that no token is needed. It does not explicitly contrast with alternatives, but the use case is specific enough for an agent to select it correctly.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: it reads immediately without waiting, the heartbeat ID is a 256-bit bearer secret, and no authentication is required. These details clarify security expectations and non-blocking behavior 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 compact and front-loaded with the core action. Each sentence earns its place: what the tool does, what it inspects, the non-waiting behavior, and the security-relevant bearer-secret/no-auth clarification. There is no filler or repetition of schema details.

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-only tool with an output schema, the description covers the essential context: what state information is available, that it is non-blocking, that the ID is a secret, and that authentication is not required. Nothing an agent needs to decide whether to call this tool 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% and the single parameter is already described as the secret heartbeat ID returned by create_heartbeat. The description adds further meaning by emphasizing that the ID is a 256-bit bearer secret and that no authentication is required, which goes beyond the schema and helps the agent handle the parameter correctly.

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 ('Read one heartbeat immediately') and then enumerates exactly what can be inspected: armed, missed, fired, expired, running late, and next deadline. This distinguishes it from the sibling create_heartbeat and ping_heartbeat by focusing on immediate status inspection rather than creation or waiting.

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 intended use ('Use it to inspect whether...') and explicitly notes that it does not wait for a state change, which guides an agent away from using this tool for blocking or state-transition waiting. It does not name a specific alternative tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail: group semantics, what the group view contains and never contains, the effect of wait_seconds, and the lack of authentication requirements. No annotation contradiction 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 purpose is front-loaded, and the remaining sentences each carry essential information: group behavior, group-view privacy constraints, wait behavior, and authentication requirements. 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 simple read tool with a known output schema and safety annotations, the description covers everything an agent needs: what action to read, polling semantics, group interpretation, privacy boundaries, and auth requirements. Nothing essential is missing.

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

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

Schema description coverage is 100%, and both parameters already have descriptive text. The description reinforces action_id as the UUID from create_human_approval and frames wait_seconds as waiting 'for a change,' but it does not add substantial parameter meaning 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?

The description opens with a specific verb and resource: 'Check whether the person has answered a form from create_human_approval, and read the answer.' It clearly ties the tool to its create-sibling and distinguishes it from the other read tools available.

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 gives strong contextual guidance: it tells when to use it (after create_human_approval), explains partial vs. answered for groups, and prescribes wait_seconds behavior from 1 to 25 or 0 for immediate reads. It does not explicitly name alternatives or exclusions, but the usage context is clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: the 24-hour lifetime, failure on unknown ID, and the instruction to treat failures as permanent rather than transient. It also clarifies that no API key or account is required. These details are not captured by annotations and significantly improve the agent's ability to handle errors correctly.

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 well-structured and front-loaded with the primary purpose. It is composed of three sentences that flow logically: purpose, failure behavior, and authentication. It avoids redundancy with annotations and schema. While it is slightly verbose with the sha256_hash detail (which may not be essential for calling the tool), it remains clear and efficient overall.

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 is simple (one parameter, output schema exists), and the description covers all essential aspects: what it does, how to interpret failures, and that no auth is needed. Combined with annotations that already declare readOnly and idempotent, an agent has everything required to call it correctly and handle responses appropriately. No critical information 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?

The input schema already provides a description for storage_id ('The UUID that store_temporary_data returned.'), and the schema coverage is 100%. The tool description adds little about the parameter itself beyond restating its origin; the mention of sha256_hash appears to relate to the output or validation but is not directly tied to the input parameter. Since the schema fully documents the parameter, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Fetch back a JSON value that store_temporary_data saved earlier' and 'Returns the value exactly as it was stored.' It specifies the resource (JSON value) and the verb (fetch back), and it distinguishes itself from the sibling store_temporary_data by explicitly referencing it. The failure semantics are also clearly outlined, which further clarifies the tool's role.

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: it should be used to retrieve a value previously saved via store_temporary_data. It provides concrete guidance on how to interpret failures ('treat a failure as expired or never written rather than as a temporary fault worth retrying'), which is valuable operational context. It does not explicitly list alternative tools or when not to use it, but the direct counterpart reference makes the use case clear enough for an agent.

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 and idempotentHint, and the description adds significant behavioral detail beyond that: status semantics, pending not being a failure, early return when capture changes, zero meaning immediate read, unknown/expired IDs failing, and no-auth direct invocation. There is no contradiction with 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?

Four compact, front-loaded sentences cover purpose, status semantics, waiting behavior, edge cases, and authentication. Every sentence earns its place; there is 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?

Given the output schema, full parameter documentation, and read-only/idempotent annotations, the description covers all necessary operational details: status interpretation, waiting strategy, early return, failure cases, and invocation prerequisites. Nothing essential for correct use 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%, and the description adds further meaning: it explains the effective use of wait_seconds (1-25 for efficient waiting), the early-return behavior, and that zero reads the current state immediately. This goes beyond the schema's basic parameter constraints and enriches agent understanding.

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: 'Check whether anything has been sent to a capture URL yet, and read it.' It clearly distinguishes the tool as a read/status operation and defines the status values (pending/captured), preventing confusion with capture creation or other sibling 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 practical usage guidance: pending is a normal state, wait_seconds can be used to wait efficiently with early return on change, and zero returns immediately. It also explains that no API key, account, or signup is needed. It stops short of explicitly naming create_webhook_capture as the complementary tool, but the create/read relationship is clear from the sibling context.

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 meaningful behavioral details beyond the annotations: the receipt is invalidated, a fifth claim makes the job failed, and stale receipts cause conflicts. This gives an agent crucial side-effect and edge-case information that annotations alone do not provide.

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 deliver distinct information: core action, failure threshold, and receipt lifecycle. The description is front-loaded and every sentence earns its place without 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 mutating tool with an output schema and destructive annotations, the description covers the main preconditions and side effects: the job must be claimed, the worker needs the current receipt, receipt invalidation, and the fifth-claim failure. It does not spell out every error response, but the output schema and annotations cover part of that 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?

With 0% schema description coverage, the description compensates by explaining the two least obvious parameters: the worker token acts as the credential and the receipt must be 'current', with stale receipts conflicting. queue_id and job_id are not elaborated, but their roles are largely self-evident from their names and the required-parameter 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 opens with 'Return a claimed job to pending', a specific verb and state transition that clearly identifies the tool's purpose. It also distinguishes this from siblings like claim_agent_queue_job and ack_agent_queue_job by specifying the release action and the required token/receipt.

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 intended usage is clear: a worker that previously claimed a job wants to return it to pending. It does not explicitly name alternatives or state when not to use it, but the state-transition language and sibling list make the context apparent without ambiguity.

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 this is a mutating, non-idempotent, non-destructive operation. The description adds valuable context: it releases the lease before TTL ends, requires the secret owner token, and explicitly states 'No authentication is required.' This goes beyond the annotations by clarifying the authorization model and the effect on other agents. It doesn't mention what happens to the lease's data or whether the release is permanent, but the core behavior is well disclosed.

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: the action and purpose, the usage condition, and the required token plus auth note. The most important information is front-loaded. No fluff or repetition of schema details.

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 mutating lease operation with a clear schema and output schema, the description covers the essential context: when to use it, what it does, and the key prerequisite. It could mention what the response contains or what happens to the lease after release, but the output schema likely covers that. The description is complete enough for an agent to select and invoke the tool 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 the schema already documents all three parameters thoroughly. The description adds the context that owner_token is the 'secret owner token' and that it is required, but this is also in the schema. The description does not add new parameter-level meaning beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly states the action ('Give up a lease before its TTL ends'), the resource ('a lease'), and the purpose ('so another agent can acquire the work'). It also distinguishes the tool from siblings like renew_lease and complete_lease by specifying the use case of abandoning work without a reusable result.

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 explicitly says when to use this tool ('when abandoning work without a reusable result') and implies when not to use it (when there is a reusable result, presumably complete_lease). It also mentions the required secret owner token, which is a key prerequisite. This is strong guidance for an agent deciding between release_lease and related lease 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?

The description goes well beyond annotations by disclosing that visibility is capped by the original queue expiry, that stale/expired receipts are conflicts, and that overall queue lifetime is never extended. This gives an agent critical stateful behavior without contradicting the readOnly/idempotent/destructive hints.

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

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

Three tight sentences lead with the core action, then pack the timeout constraints, conflict case, and lifetime caveat. Every sentence contributes information and there is no filler or repetition of the 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 an output schema present and annotations already marking this as non-read-only and non-idempotent, the description covers the important behavioral edge cases for a renewal call. It is only slightly incomplete in not explicitly stating that the worker must already hold the claim and that the response likely returns a refreshed receipt, though 'current receipt' strongly implies this.

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 description adds meaning to visibility_timeout (30-900 seconds, default 60, capped by queue expiry) and clarifies that receipt must be the current receipt. However, it leaves the roles of queue_id, job_id, and worker_token mostly to inference from naming and schema patterns.

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 the specific action 'Move the active claim deadline', naming both the operation and the resource. This clearly distinguishes renewal from sibling actions like ack_agent_queue_job, release_agent_queue_job, or claim_agent_queue_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 description implies renewal is only valid while a claim is active and a current receipt is held, and it gives constraints on visibility_timeout. However, it never explicitly says 'use this when you need more processing time for a claimed job' or contrasts it with ack/release alternatives, so the usage context is more implied 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 declare non-read-only, non-idempotent, and non-destructive. The description adds important behavioral details: renewal cannot move the absolute 24-hour limit, no authentication is required, and the owner token must stay secret. These go beyond the annotations and help the agent understand side effects and security constraints.

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 concise sentences, front-loaded with the action and key constraints. No unnecessary words 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?

Given the presence of an output schema and detailed annotations, the description covers all necessary usage aspects: when to use, the 24-hour limit, authentication, and owner token security. No critical information for calling the tool 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 75% (key, namespace, owner_token have descriptions; ttl_seconds lacks a description). The description itself doesn't add parameter-specific details beyond what the schema already provides, so it doesn't significantly enhance understanding. Baseline of 3 is appropriate given the high schema coverage.

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 action ('Extend a lease'), the resource ('a lease that this caller still owns'), and a key constraint ('cannot move the absolute 24 hour limit'). It clearly distinguishes from siblings like acquire_lease, complete_lease, and release_lease by focusing on extension of an existing lease.

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 provides a clear usage condition: 'Use it before the current TTL ends when work is still running.' It also notes that renewal cannot extend beyond the absolute limit. However, it doesn't explicitly mention alternatives like complete_lease or release_lease, though the context implies them.

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 list all hints as false, indicating no special flags, but the description adds key behavioral details: no authentication required, the 24-hour expiration, and the redirect mechanism. This goes beyond the annotations to clearly set expectations.

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 concise sentences: states the core function, gives usage context, and warns about the 24-hour limit. Every sentence adds value, with no fluff.

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 tool with an output schema and annotations, the description covers purpose, usage, and constraints comprehensively. No gaps remain for expected behavior.

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 schema covers 100% of the parameter (long_url) with a clear description and format. The tool description does not add extra parameter-level detail, but the schema already provides sufficient meaning. Baseline of 3 is appropriate given full schema coverage.

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 tool's function: turning a long URL into a short 307.fi link that redirects. It uses a specific verb-resource combination and differentiates itself from siblings by highlighting the temporary nature and direct usage.

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

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

Explicitly states when to use the tool (e.g., when a URL needs to be typed or pasted in constrained contexts) and when not to use it (for anything lasting over 24 hours). It also provides a clear alternative guidance by labeling it for handoffs within tasks, distinguishing it from other 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?

With no informative annotations (all hints false), the description carries the full burden and does so thoroughly: no auth required, public URL, 24-hour TTL, warning against storing secrets, and receipt verification via sha256_hash and byte length. It also explains the REST storage_url and ETag behavior, adding genuine behavioral detail.

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

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

The description is dense but well-organized: purpose, use case, authentication caveat, TTL, retrieval, and verification details all earn their place. It is longer than minimal, but the extra sentences provide high-value operational behavior rather than 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 one-parameter tool with an output schema present, the description is exceptionally complete. It covers when to use it, how to read it back, security limitations, expiration, and integrity verification, leaving an agent well equipped to call it correctly.

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

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

Schema coverage is 100% and the schema already fully documents the single data parameter, including that it accepts any JSON type. The description adds a no-secrets reminder but no additional parameter syntax or format details, 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: 'Put any JSON value somewhere another process can fetch it' and clearly identifies the returned storage_id and public read_url. It is easily distinguished from the sibling read_temporary_data, which retrieves the value.

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 use contexts: handing results to another agent, script, webhook receiver, or later run when no shared filesystem or database exists. It also points to read_temporary_data for retrieval, though it does not explicitly list when not to use this tool versus queue/inbox/lease siblings.

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

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

Annotations are all false, so the description carries the full burden. It discloses the auth requirement (dns_token), the non-extending expiry ('the name still disappears 24 hours after it was created'), and a rate limit ('One change per name per 10 seconds'). These are meaningful side effects beyond what the schema provides, and there is no contradiction with annotations.

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

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

Four sentences, each with a distinct role: action, prerequisite, use case, and side-effect/rate-limit. No redundant wording, and the most important information (action, prerequisite) 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 mutation tool with an output schema and a 100% covered input schema, the description covers the critical behavioral aspects: what it does, when to use it, the required credential, the expiry non-extension, and the rate limit. It omits error cases, but those are not typically required when schema and annotations already provide structural detail.

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% with detailed per-parameter descriptions. The tool description adds no new parameter-level meaning beyond reinforcing that dns_token comes from create_dns_name. Baseline 3 is correct when the schema does the heavy lifting.

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 'Change the address a temporary DNS name points at,' a specific verb+resource statement that clearly differentiates the tool from its siblings (create_dns_name, delete_dns_name, read_dns_name). The title and description align and no ambiguity remains about what operation is performed.

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 provides an explicit trigger: 'Use it when the machine behind the name moved and you would rather keep the name than hand out a new one.' It also names the prerequisite dns_token from create_dns_name. While it doesn't explicitly contrast with delete_dns_name or read_dns_name, the use case is clear enough for an agent to route correctly.

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