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?

Adds substantial behavior beyond the annotations: the 500-note lifetime limit that counts deleted notes, retention until collection expiry, rate-limit budget shared with search, Retry-After on refusals, and a secrets/PII warning. Annotations only confirm it is a non-idempotent, non-read-only, non-destructive write.

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

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

Dense but front-loaded: batch size, auth, note shape, then limits, rate limits, and retry policy in order of importance. Nearly every sentence carries actionable information, though the closing 'no API key, no account, no sign up' line is marginal padding.

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 no output schema and thin annotations, the description covers auth, limits, retention, rate limiting, and failure handling well. It stops short of explaining what a reused note key does (upsert vs. duplicate) — a notable gap given the non-idempotent annotation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by documenting constraints the schema omits: text of 1-2000 characters, an optional key of up to 64 allowed characters, and the 1-32 batch bound. The write_token's role is also spelled out beyond the schema text.

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

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

States a specific verb and resource ('Add ... notes') with the target ('semantic search collection') and batch semantics. It is trivially distinguishable from siblings like create_semantic_search, query_semantic_search, delete_semantic_search_note, and read_semantic_search.

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

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

Gives strong operational usage context: the write token is required, sharing a 60/min and 1000/day per-IP budget with search, refusal Retry-After handling, and an explicit 'do not retry automatically' instruction. It does not explicitly name when to prefer a sibling (e.g. delete or query), but the tool's scope makes that largely implicit.

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 destructiveHint=true and idempotentHint=true with readOnlyHint=false; the description adds the precondition failure mode (an ended job can't be cancelled). It doesn't restate idempotency, which annotations already cover. The auth disclosure ('No API key...call it directly') is useful additional context.

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

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

Three short sentences, front-loaded with the action and its precondition. The auth sentence is somewhat tangential but brief.

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 destructive mutation with annotations covering safety, the description supplies the key missing behavioral fact (cannot cancel a finished job). It could note what cancellation does to the schedule record, but is largely complete.

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

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

One required parameter with 0% schema description coverage. The description does not explain schedule_id's format, even though the schema pattern defines a UUID. Baseline 3 for a single-param tool where the name is self-explanatory, but the description adds no 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?

States a specific verb (cancel) and resource (scheduled webhook), and adds a scope qualifier ('that has not finished'). Clearly distinguishes this from sibling schedule_webhook and read_webhook_schedule.

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

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

Gives a clear precondition for when the tool can be used ('has not finished') and what happens otherwise ('A job that has already ended cannot be cancelled'). No sibling alternatives are named, but the when-to-use condition is explicit.

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

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

Annotations 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?

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so credit goes to what is added: the disclosure that the response echoes what the input was parsed as, which mitigates ambiguity risk for 10- vs 13-digit timestamps. The auth-free statement is also useful context not present in annotations. No return-shape or error behavior is described, keeping it below 5.

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

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

Three sentences, front-loaded with the core conversion and output formats, followed by offset semantics and the auth note. Dense and mostly waste-free, though the 'No API key, no account and no sign up' clause is slightly redundant phrasing for a single fact.

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

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

With no output schema, the description does supply the output formats and states that the response reports how the input was interpreted, covering the main ambiguity an agent faces. It stops short of describing default behavior when offset is omitted or what happens on unparseable input, which would round it out.

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 baseline is 3 and the schema already documents 'value' and 'offset'. The description adds genuine meaning: it clarifies that both seconds and milliseconds timestamps are accepted, and that offset determines the zone of the answer rather than the input – a semantic role the schema's pattern alone does not convey.

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

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

States a specific verb (convert) and resource (timestamp/date) plus the concrete output forms (Unix, ISO 8601, RFC 2822, UTC). However, it never names or distinguishes itself from the closely related siblings list_timezones, time_formats, and get_current_time, leaving the agent to infer which is appropriate.

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

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

Usage is implied by listing accepted input types (Unix seconds/ms or date text) and the role of offset, which lets an agent infer when the tool applies. There is no explicit when-not guidance and no mention of how it relates to time_formats or get_current_time. The auth note ('call it directly') is a small precondition add.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful non-annotation context: the output is a PNG at error correction level H, and it explicitly states no API key/account/signup is required and that it can be called directly, which reduces invocation friction.

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

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

Two tight sentences, front-loaded with the core action and output format, followed by the access prerequisite. 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 one-parameter tool with read-only/idempotent annotations and no output schema, the description covers purpose, output format, and access requirements. It stops short of noting the input length limit, but is otherwise sufficient 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 0%, so the schema documents no parameter semantics. The description says the input is 'a text or URL' but does not mention the 1-2000 character bounds or that 'text' is the sole required field. Baseline consideration of a single-param tool keeps this at 3, but the description does not fully compensate for the coverage gap.

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

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

States a specific verb and resource ('Make a QR code for a text or URL') and adds the output format (PNG, error correction level H). This clearly distinguishes it from the sibling read_qr_code, which does the inverse.

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?

Implies the use case (encoding text/URL into a QR image) but offers no explicit when-to-use or when-not guidance, nor does it name alternatives. Adequate but leaves routing to inference.

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

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

Goes well beyond the annotations (which only signal non-read-only, non-idempotent, non-destructive). It discloses the 24-hour non-extendable lifetime, that read/write bearer tokens are returned once and must be kept secret, the 500-note cap, the 20-collections-per-IP limit, and the model-fixing behavior. These are exactly the operational constraints an agent needs before calling.

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

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

Front-loaded with purpose, then lifetime, model, return values, limits and auth in a compact flow. Slightly dense and the model enumeration partially repeats the schema, but nearly every sentence carries distinct, decision-relevant 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?

With no output schema, the description compensates by explaining that it returns a collection_id and separate read/write tokens, plus all lifetime, quota and auth constraints. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the enum plus default are already in the schema, so baseline would be 3. The description adds meaningful semantics by noting the model 'stays fixed for the collection', which is behavioral information the schema does not convey.

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

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

States a specific verb (Create) and resource (a semantic search collection) and immediately clarifies what it holds: short notes that agents search by meaning across wording and languages. This clearly distinguishes it from siblings like add_semantic_search_notes, query_semantic_search and read_semantic_search.

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

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

Gives strong operational context – 'call it directly' with no API key, account or signup – which tells the agent this is a frictionless entry point. It does not, however, explicitly state when to use this versus the add/query/read siblings or that it must precede them, so usage is clear but not fully routed.

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?

Annotations cover safety (readOnlyHint, openWorldHint, idempotentHint=false), and the description adds genuinely new behavioral context: the private key is sent once, not stored, but has transited the service, so it is test-grade only. It also names the actual data sources (blockchain.info, an Ethereum RPC node, Solana mainnet RPC), which nothing else discloses. A shadow of doubt remains about whether 'new_wallet' truly fits readOnlyHint, but no direct contradiction.

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

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

Two dense sentences with no explicit division between the balance path and the wallet-generation path, so the structure doesn't front-load the two distinct operations. The security caveat is placed mid-sentence rather than as a prominent warning.

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 3-parameter enum-driven tool with no output schema, the description covers both operations, the data sources, the no-auth model, and a critical security caveat about generated keys. What an agent needs in order to call it correctly is largely present; only the return shape of the balance call is left implicit.

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 only 33%, so the description must compensate. It clarifies that the address is a public address used for balance, and the enums for chain and operation are self-documenting. However, it never states that 'address' is unused/optional for new_wallet, leaving that to the schema's 'balance only' note.

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 conveys the domain – reading balances of BTC/ETH/SOL addresses and generating a key pair – but does so as an awkward noun fragment rather than a clean verb+resource statement ('The balance of ... or a newly generated key pair'). There are no sibling wallet tools, so differentiation isn't the issue; the gap is that the actual actions (check balance vs. generate wallet) are implied rather than stated.

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

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

It gives one real usage constraint ('use it for tests and small amounts only' for generated keys) and reassures the caller no API key or account is needed. It does not explain when to pick the 'balance' operation versus 'new_wallet', nor any prerequisites for reading an address, leaving the choice to the schema enums.

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 read-only, open-world, non-idempotent, but the description adds substantial context the annotations cannot: request/answer bodies are not stored while usage counters are, exact size limits (8 KiB, 3 KiB for tev1), question/choice caps, per-minute and per-day rate limits, Retry-After semantics, and a 'do not retry automatically' warning. This is exactly the kind of operational detail an agent needs.

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 content is valuable but delivered as a long, run-on block mixing modes, limits, rule syntax, and privacy notes without clear structure. It is front-loaded on the mode choice, but the density makes it harder to scan than necessary; some clauses could be tightened or grouped.

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

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

With no output schema, the description carries the return-value burden and does so partially, stating that model mode returns structured answers without an automatic action or rule trace. Combined with the rule format, limits, and no-key/auth info, an agent has enough to invoke correctly, though the exact response shape for rules mode is left to the linked docs.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by documenting the rule DSL: each rule is {"if": condition, "weight": number} with operators eq/ne/gt/gte/lt/lte/in/exists/prefix/contains combined via any and not, and clarifies that state holds the facts. That meaningfully enriches the otherwise opaque nested-object parameters.

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

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

The description names a specific verb (Decide) and clearly distinguishes two modes: the rules engine (yes_no, choice, scale) and model mode (clef, nimble, tev1). It explains what each mode does, though the opening sentence is dense and slightly awkward to parse. It does not name a sibling tool, but none of the listed siblings are near-neighbors for this capability.

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 routing: omit model/use rules for the rule engine, use clef/nimble/tev1 for noul/choice/score questions with instructions and criteria. It even characterizes tev1 as smallest, fastest, English-only, suited to short direct questions. No explicit 'when not to use' or alternative tool is named, but the mode-selection guidance is strong.

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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds genuinely non-obvious behavior beyond them: what is destroyed (text and vector), that removal from search is immediate, and that the note's slot in the 500-note lifetime quota stays consumed. It also states the auth model (no API key/account).

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, front-loaded sentences that put the action first and the quota caveat before the auth aside; no filler sentences. The 'no API key, no account and no sign up' triplet is slightly redundant for emphasis, keeping it just under a 5.

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

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

For a destructive mutation with full annotation coverage, fully documented parameters, and no output schema, the description supplies everything an agent needs: destruction scope, immediate effect, quota persistence, and the auth model. Nothing material 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 each parameter documents its own origin (write_token from create_semantic_search, note_id from add_semantic_search_notes or a search). The description only references 'the write token' and adds no syntax or format detail, so 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 gives a specific verb (Delete) and resource (one note in a semantic search collection), and 'one note' implicitly contrasts with the plural sibling add_semantic_search_notes. It stops short of naming a sibling or the read/query counterparts, so it is clear but not fully differentiated.

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

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

It states you call it 'directly' with no API key, which is a usage precondition, and the singular scope hints at single-note deletion. But there is no explicit when-to-use vs when-not-to-use guidance and no reference to the alternative of leaving notes in place.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds genuinely new behavior: decode returns decoded_text for UTF-8 vs decoded_base64 for binary, base58 uses the Bitcoin alphabet with a 64 KiB cap, base64url is unpadded, and url uses RFC 3986 with %20 for space. It stops short of describing error behavior on invalid input.

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

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

Front-loaded with verb + formats, followed by return-value and format-detail sentences; the closing no-signup line earns modest place as invocation guidance. Dense but free of filler.

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

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

With no output schema, the description correctly explains the two possible return fields and the format-specific constraints. It is complete enough to call correctly, though it omits error/invalid-input behavior and the 250000 maxLength from the schema.

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

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

Schema coverage is only 33% (format and operation enums are undescribed), so the description must compensate, and it does: it pins down Base58 alphabet/limit, base64url padding, and URL percent-encoding semantics. The operation enum is self-explanatory, so full marks aren't warranted.

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 precise verb (encode/decode) and resource (text/string) across an explicit list of formats, so an agent can immediately tell it apart from siblings like hash_data, validate_value, or html_markdown_convert.

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

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

Usage is largely implied by the tool's nature, but there is no explicit when-to-use guidance or contrast with adjacent tools such as hash_data or validate_value. The 'call it directly, no API key' note addresses friction, not tool 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 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?

Annotations already declare readOnly/openWorld/idempotent hints, and random generation is consistent with idempotentHint=false. The description adds useful output context (passphrase returns entropy in bits) and default behavior, though it doesn't elaborate on return format for other kinds.

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?

One dense sentence enumerates the variants with defaults and ranges, followed by the sibling pointer and the no-auth note; front-loaded with the core purpose. Slightly long but every clause carries 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?

With no output schema, the description compensates by describing what each kind returns (e.g. color as #rrggbb, entropy bits for passphrase). Adequate for a 5-param tool, though it could note error behavior for out-of-range values.

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 80% (min/max ranges documented), and the description adds the missing defaults (number 1-6, password length 12, passphrase groups 4) plus the semantic mapping of each parameter to its kind, which is 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?

States a specific verb+resource and enumerates every generated variant (number/color/guid/password/passphrase) with their modifiers, so an agent knows exactly what the tool produces. It also names the sibling generate_uuid and the condition that routes there.

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

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

Explicitly says 'For a UUID use generate_uuid,' giving one clear alternative and when to pick it. It also clarifies there is no API key/account/sign-up requirement, which aids invocation, but gives no when-not guidance for the other random kinds.

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 already cover the safety profile (readOnly, idempotent, closed-world), and the description layers on real behavioral context beyond them: a 200-calls-per-day limit on password hashes, salted slow-by-design output returned as a self-describing string, output format differences (hex vs. integer for crc32), and a no-auth requirement.

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

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

Front-loaded with the core action and algorithm list, dense with useful detail, and no filler sentences. It runs long as a few compound sentences but every clause conveys selection or behavioral 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?

Without an output schema, the description correctly explains return formats (hex digest, integer for crc32, self-describing string for password hashes) and covers rate limiting and auth needs. The only meaningful omission is the input-size bound on the data parameter.

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 must carry the burden. It does explain the algorithm parameter by grouping the enum members semantically (integrity vs. legacy vs. password), which adds meaning beyond the raw enum. However the data parameter — its string type and 250,000-character cap — is never addressed, leaving a required input undocumented.

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

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

Opens with a concrete verb+resource (hash text) and enumerates the algorithm family, so the agent immediately understands it's a one-shot hashing utility. It clearly contrasts itself with neighboring utilities like encode_data or generate_random by naming cryptographic vs. password-hash modes.

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

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

Gives explicit selection guidance: sha256/sha3_256/blake2b/blake3 for integrity checks, md5/sha1 only for legacy systems expecting them, and argon2id/bcrypt/scrypt for test-data password hashing. It does not route the agent to the sibling verify_hash tool for the verification half of the workflow, which would be the natural companion.

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?

Goes well beyond the annotations (readOnly/idempotent/openWorld=false) by disclosing exactly what html_to_markdown strips (scripts, styles, forms, media) and returns (markdown plus page title), and how markdown_to_html handles raw HTML (rendered as text) and unsafe link schemes (rendered as their text). This is concrete behavioral detail that materially affects safe invocation.

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

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

Front-loaded with the core action, then dense per-direction detail, with no filler. Slightly long and comma-heavy, but each clause carries real information about output 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?

No output schema exists, so the description correctly explains return values for both directions (markdown + title, or html). Combined with the safety and auth-free context, an agent has everything needed to call it correctly.

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

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

Schema coverage is 50%, with the direction enum and data field documented in the schema. The description adds meaning by explaining what each direction value actually produces and its safety handling, compensating for the gap on direction semantics; data itself is only lightly described.

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

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

States a specific verb+resource (convert HTML<->Markdown) and the two direction modes, so the agent knows exactly what the tool does. It does not explicitly differentiate from the closest sibling html_to_pdf, relying on the resource name to distinguish, which keeps it just below a 5.

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

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

Gives clear rationale for when each direction is useful ('so a fetched page reads with fewer tokens' for html_to_markdown, 'so the html can go into a page as it is' for markdown_to_html). It never names an alternative tool or states when-not to use it, so no explicit exclusion guidance.

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

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

The description adds substantial behavior beyond the annotations: JavaScript and network access are disabled, only submitted HTML is used, images must be inline data URLs, and the resulting PDF is stored for 24 hours with storage_id and storage_url. These details are exactly what an agent needs to invoke the tool safely and interpret the result.

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 text is front-loaded with the core rendering behavior, then proceeds through options, storage lifetime, retrieval, and auth requirements. Every sentence adds actionable information without padding.

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 nested options object, no output schema, and annotations that leave storage and retrieval behavior unstated, the description is complete enough for correct invocation. It explains the output shape, where the file goes, and how to read it back.

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 carries the parameter burden and does so well. It documents the html input constraints (no external network, inline data URLs required) and enumerates the options keys with valid page sizes, orientations, and margin examples such as 10mm.

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 pair: render HTML to a PDF. It is immediately distinct from siblings such as process_image or read_stored_file, and the opening sentence leaves no ambiguity about what the tool produces.

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 clear operational context: no API key or sign-up is needed, the output is stored for 24 hours, and read_stored_file retrieves it. It does not explicitly state when not to use this tool or name an alternative renderer, but the retrieval follow-up and auth guidance are useful usage cues.

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 readOnlyHint=false and openWorldHint=false, and the description explains why: results are persisted for 24 hours and returned with a storage_id and storage_url, which reconciles the non-read-only hint. It also discloses the auth posture (no API key, account, or sign-up). It stops short of mentioning the 250,000-character input limit or how to retrieve the stored artifact later (read_temporary_data), which would have completed the behavioral picture.

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

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

Three tight sentences, front-loaded with purpose before mode semantics and then retention/auth facts. The closing 'No API key, no account and no sign up' is mildly redundant phrasing, but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by naming storage_id, storage_url, and validate's error location. The one real gap is that it never says how the 24-hour artifact is retrieved, leaving the agent to discover read_temporary_data on its own.

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%, with mode and indent described only as 'format only.' and operation undescribed. The description compensates by clarifying that mode selects pretty (with indent 2 or 4) versus compact, tying indent to the pretty path and explaining that validate ignores those options - meaningfully more than the schema conveys.

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

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

The description names a specific resource (JSON text) and enumerates both verbs (format, validate), so an agent immediately knows the tool's scope. It does not, however, explicitly route away from adjacent siblings such as json_csv_convert or validate_value, so it falls short of the top tier that requires sibling differentiation.

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 explains what each operation does in practice - format pretty-prints or compacts, validate reports whether it parses and where it breaks - which gives clear selection context between the two modes. It never states when NOT to use the tool or names an alternative for cases like JSON-to-CSV conversion, so no exclusions are provided.

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?

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the 5000-flat-object cap, the 24-hour result retention, that the response carries storage_id and storage_url, and crucially that no API key or account is needed. These are real operational facts an agent must plan around; only error/failure behavior is left unstated.

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

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

A single dense paragraph that is front-loaded with the core purpose before mode details, limits, and storage behavior. Nearly every clause carries information, though the delimiter enumeration duplicates the schema enum and could be trimmed.

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

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

With no output schema, the description correctly compensates by describing the return payload (storage_id, storage_url) and retention window. It covers inputs, limits, delimiter options, and auth posture for a 6-parameter tool, leaving only edge-case/error behavior unspecified.

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 schema coverage at 67%, the description usefully clarifies parameter roles the schema only tags as 'json_to_csv only' or 'csv_to_json only', and explains spreadsheet_safe beyond the schema as guarding cells a spreadsheet would execute as formulas. The delimiter enumeration (comma/semicolon/tab) merely restates the enum, keeping it short of a 5.

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

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

States a specific verb and resource ('Convert between JSON rows and CSV') and enumerates both operating modes with the inputs each consumes (json_to_csv takes columns and rows; csv_to_json takes data). An agent can immediately tell what the tool does and which direction to pick, with no sibling in the list (convert_timestamp, encode_data) overlapping this function.

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 effectively routes the agent by mapping each direction to its required input ('json_to_csv takes columns and rows', 'csv_to_json takes data, the CSV text'), so the choice is unambiguous. It lacks explicit exclusions or a stated 'use X instead' comparison, but for a self-contained converter that is a minor gap.

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?

Adds real behavioral context beyond the annotations: the secret is used only for this call and is not persisted, and no API key or account is required. It also discloses that decode validates exp, nbf and iat, which the schema does not state. The readOnly/idempotent annotations remain consistent since no state is stored.

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

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

Three tight sentences, front-loaded with the tool's purpose and then the mode semantics. The closing 'No API key, no account and no sign up' sentence is slightly redundant with the preceding 'secret is not stored' claim, but still conveys the auth-free calling model.

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

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

With no output schema, the description covers return values by naming them ('answers jwt' and 'answers decoded_payload'), plus the auth model and the per-call secret handling. An agent has everything needed to call either mode 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 50% (token and payload documented, secret and operation not), so the description must compensate. It does so by defining what each operation does and which parameter belongs to which mode, adding the timestamp-claim semantics for decode that the schema omits.

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

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

States a specific verb and resource ('Create or check an HS256 JSON Web Token') and spells out both modes: encode signs a payload, decode verifies a token. This distinguishes it clearly from computational siblings like hash_data, encode_data and verify_hash, which operate on different primitives.

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 encode/decode split and the 'decode only'/'encode only' parameter roles imply when each mode applies, and the token expiry claims (exp, nbf, iat) hint at verification use. However, there is no explicit when-to-use/when-not guidance or routing to a sibling tool for adjacent tasks such as hashing or signing non-JWT data.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context by noting no API key, account or sign-up is required, telling the agent it can invoke directly without credentials. It does not describe response size or pagination, which keeps it short of a 5.

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

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

Two sentences, front-loaded with the core action and the optional filter before the access note. The final sentence is mildly promotional but does carry real information about auth, so it earns its place; nothing is redundant.

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

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

For a single-optional-parameter, no-auth read tool with no output schema, the description covers what is returned (timezone names plus current offsets) and how to narrow results. Only the exact return shape and result volume are unstated, which is a minor gap for a tool this simple.

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 there is only one optional parameter, so the schema already documents 'offset' with a regex pattern and range. The description's '+0530' example reinforces the format but adds nothing the schema does not already state, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the IANA timezones') plus what is returned ('with their current UTC offsets') and the optional narrowing ('only those at one offset such as +0530'). This distinguishes it from siblings like convert_timestamp, time_formats and get_current_time, which deal with time but not timezone enumeration.

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 the 'offset' argument is useful ('optionally only those at one offset'), but never names an alternative tool or states when to prefer this over convert_timestamp or time_formats for timezone-related questions. Context is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and idempotency are covered structurally. The description adds useful operational context (no auth needed) and notes the GeoLite2 source, but does not describe accuracy limits, data gaps, or fallback behavior for unresolvable inputs.

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

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

A single front-loaded sentence enumerating all four kinds, followed by a short operational note. No padding, though the listing is dense and could be slightly easier to scan if split.

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 2-parameter read-only lookup with no output schema, the description covers all four modes, the meaning of 'value', and the auth contract. Missing only edge-case behavior (what happens on invalid IP/domain or resolution failure), which is minor for a simple lookup.

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

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

Schema coverage is 50% – 'value' is documented in the schema, but 'kind' is an enum-documented param whose semantics are partially in the description. The description maps 'value' to its meaning for reverse_ip and domain_ip, roughly maintaining the baseline expected when the schema carries half the load.

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 enumerates the four concrete facts the tool returns (client IP, user agent, geo lookup for an IPv4, first IPv4 of a domain), which distinguishes it from generic network utilities among the siblings. It is specific about the resource and the modes of operation.

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

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

It states the operational contract clearly ('no API key, no account and no sign up: call it directly') and ties each 'kind' to its behavior, giving the agent enough to invoke without prerequisites. It doesn't name alternatives, but no sibling overlaps this purpose, so exclusions are less critical.

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 readOnlyHint=false and idempotentHint=false, but give no hint about persistence. The description adds genuinely new behavior: matches are stored as JSON and kept for 24 hours, plus the no-auth requirement. It stops short of saying how the stored result is later retrieved, but the TTL disclosure is valuable context beyond the annotations.

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

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

Purpose is front-loaded, followed by the parameter format and the storage caveat. The closing 'No API key, no account and no sign up: call it directly' is somewhat redundant but adds operational value. Overall tight with minimal waste.

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 3-required-param tool with no output schema and 0% schema coverage, the description covers purpose, input shape, TTL, and auth. It would be fully complete if it explained how the stored 24-hour result can be read back, since no output schema exists to document the return value.

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 carries the full burden. It defines left/right as lists of row objects and explains keys as pairs with a concrete example ({"left":"id","right":"customer_id"}), which compensates well. It omits the maxItems=100 limit and does not fully describe the keys object shape, keeping it from a 5.

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

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

States a specific verb and resource ('match the rows of two tables on pairs of key columns, like a join') and names the storage side effect. An agent immediately understands this is a table-join operation, which is clearly distinguishable from the surrounding utility siblings.

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?

'call it directly' with 'no API key, no account and no sign up' tells the agent it can be invoked without setup, which is useful operating context. However, there is no explicit when-to-use vs when-not guidance or named alternative, so usage remains implied rather than stated.

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

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

Annotations 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 declare a non-read-only, non-destructive, non-idempotent, non-open-world tool, and the description adds genuinely useful behavioral context: results are stored for 24 hours, the response carries a storage_id enabling chained calls, and no API key or account is required. It does not clarify that 'strip' discards EXIF/XMP/IPTC irreversibly or specify payload size limits beyond the schema, but it goes well beyond the annotations.

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

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

A single dense paragraph, front-loaded with the resource and then a parenthetical parameter-to-operation map, followed by input sourcing and storage/chaining notes. Every sentence carries information, though the long parenthetical enumeration is packed tightly enough to be slightly hard to scan.

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 13-parameter, no-output-schema tool, the description covers input sourcing, format constraints per operation, the 24-hour result retention contract, and chaining via storage_id. Return-value details for metadata/colors/favicon are only implied, which is a minor gap given no output schema exists.

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 schema description coverage at only 23% across 13 parameters, the description compensates substantially by naming each parameter inline and binding it to an operation (format, quality, lossless, width, height, fit contain/cover, upscale, crop fit/trim/center, name, count, metadata, strip). It omits value ranges that the schema actually supplies (quality 40-95, count 2-16), so it is strong but not complete.

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 concrete resource (images in JPEG/PNG/WebP/HEIC/GIF) and enumerates the exact operations it performs: convert, compress, resize, metadata, strip, colors, favicon. An agent can tell what this tool does without opening the schema, and no sibling tool overlaps with image processing.

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 maps each operation to its relevant inputs (e.g. 'HEIC for convert and resize', 'GIF for metadata and strip') and routes the agent to the alternative input path ('store it with REST POST /services/v1/storage first and pass storage_id'). It lacks explicit when-not-to-use guidance, but the operation-to-format mapping is clear practical 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, yet the description adds substantive context: no API key/account needed, the exact scoring formula, the 1-10/default-3 limit, and the caveat that scores are cosine similarity rather than probabilities and results are suggestions, not confirmed matches. It stops short of describing error behavior or missing-token handling.

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 length is justified because there is no output schema and the score semantics are non-obvious. The scoring rules (code prefixes, three-or-more-digit numbers, '1 200 read as 1200') are dense and border on over-specification, but they are load-bearing for interpreting results.

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

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

With no output schema, the description usefully enumerates returned fields (note_id, key, text, score) and the score's meaning, and confirms the auth model. It omits failure modes (invalid token, unknown collection) and the max length of query, leaving a couple of gaps for a 4-parameter tool.

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

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

Schema coverage is 50% (limit and query are undocumented in the schema), and the description compensates well: it states the limit range and default, and explains how query tokens (identifiers, code prefixes, multi-digit numbers) affect scoring. That meaningfully exceeds what the schema provides for those two parameters.

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

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

States a specific verb and resource ('Search the notes by meaning') plus the credential used, which distinguishes it from read_semantic_search and add_semantic_search_notes. It does not explicitly name the sibling tools, so an agent must infer the routing from the shared prefix.

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 implicit usage context (ranked suggestions, compare to read_semantic_search only by inference) and warns to read the text before acting, but never states when this tool should be chosen over read_semantic_search or add_semantic_search_notes, and offers no exclusions.

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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: multiple codes are returned joined by newlines, and no API key/account/signup is required. It omits rate limits and what happens when no code is found, so not a 5.

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

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

Four short sentences, front-loaded with purpose and formats, then return behavior, input choice, and auth note. Nothing is padded and every sentence carries distinct 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?

With no output schema, the description usefully explains the newline-joined return format and covers accepted formats, input paths, and auth. It lacks error/empty-result behavior and any rate or size context beyond what the schema already states.

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 schema already documents storage_id provenance, 24h expiry, and the base64 size limit. The description's "or" only clarifies that the two parameters are mutually alternative input paths, a marginal addition over the schema.

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

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

States a specific verb (read) and resource (QR codes) plus the accepted image formats (PNG, JPEG, GIF, WebP), which cleanly separates it from the sibling create_qr_code. An agent can tell what it does and what it accepts without opening the schema.

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

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

"Give image_base64 or storage_id" tells the caller how to supply input, which is real usage guidance, but there is no when-to-use/when-not context and no comparison to neighbors like process_image or read_stored_file. Usage is implied rather than framed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context by stating no API key or account is required and that the call can be made directly. It stops short of describing failure behavior for invalid/expired tokens, which is a minor gap given the readOnly annotations.

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

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

Three short sentences with the returned fields front-loaded and no filler. The fragment 'Notes are found by searching' is slightly oblique, but overall the text is efficient and appropriately sized.

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

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

With no output schema, the description correctly enumerates the returned fields (model, note counts, limit, expiry), which is the load-bearing information, and annotations cover the safety profile. Only edge cases such as invalid/expired token behavior are unaddressed, which is a minor omission for a two-parameter read tool.

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

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

Schema description coverage is 100% and both parameters (read_token, collection_id) are fully documented in the schema with patterns and provenance (from create_semantic_search). The description restates the read-token concept but adds no format or usage detail beyond the schema, so the baseline 3 applies.

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

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

The description names a concrete verb (read) and resource (a semantic search collection) and enumerates exactly which metadata fields are returned (model, note count, lifetime notes, note limit, expiry), so the agent knows it is a metadata/stats read rather than a note search. It does not, however, name query_semantic_search as the sibling for actually searching notes, so sibling differentiation is only implied by 'Notes are found by searching.'

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 an access note ('No API key, no account and no sign up: call it directly') that qualifies when this is usable, and hints that searching is a separate action, but it never names an alternative tool or states explicit when-not conditions. Usage is implied rather than specified.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), so the bar is lower; the description still adds real behavior: return type varies by content type and embedded resources are capped at 4 MB. It does not repeat the annotation claims, but also does not discuss error behavior for a missing/expired id.

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

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

Front-loads the action and resource in the first clause, then the return-shape detail, then the no-auth note. Efficient overall, though the triple 'No API key, no account and no sign up' is slightly redundant filler.

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

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

With one fully documented parameter, rich annotations, and no output schema, the description carries the exact burden it must: it explains what comes back for each content type and the 4 MB cap. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema itself documents the UUID pattern, the expiry window, and the provenance of storage_id. The description adds only the restatement 'by storage_id', so 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?

States a specific verb and resource ('Read a stored object by storage_id') and enumerates the three return shapes (JSON data, image, embedded resource). It names sibling tools only as producers (html_to_pdf, process_image) rather than distinguishing itself from lookalike readers such as read_temporary_data, so sibling differentiation is partial.

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

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

Gives clear invocation context ('No API key, no account and no sign up: call it directly') and tells the agent where a valid storage_id comes from. It stops short of stating when to prefer this tool over read_temporary_data or other read_* 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?

Goes well beyond the annotations (readOnly, idempotent, closed-world) by disclosing the 24-hour lifetime, that failures are terminal rather than transient, that sha256_hash/bytes mirror the stored values, that max_downloads produces downloads_left and consumes reads, and that no API key is required. This is exactly the operational context an agent needs and the annotations cannot supply.

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

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

Front-loaded with what it returns and what it pairs with, and each sentence carries real information. The closing 'No API key, no account and no sign up' is slightly promotional padding, keeping it just short of a 5.

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

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

Complete for a one-parameter read tool: the description covers the source of the value, lifetime, failure semantics, and the meaning of the returned metadata, while an output schema exists to formalize the shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's description already states it is the UUID returned by store_temporary_data, so the schema carries the load. The description's sha256_hash/bytes/downloads_left text describes return fields, not the input parameter, so it adds no input-side meaning beyond the baseline.

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

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

States a specific verb (fetch back) and resource (a JSON value stored by store_temporary_data), naming the exact sibling that produced the data. An agent can distinguish this from read_stored_file or read_agent_queue_job without opening any schema.

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

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

Gives clear context: use it to retrieve values written by store_temporary_data, in this or another session. It also gives explicit error-handling guidance ('treat a failure as expired or never written rather than a temporary fault worth retrying'), which is unusually actionable. It does not, however, contrast with the sibling read_stored_file, so it falls short of the when-not/alternatives bar.

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