AI SENSE Free Public Tools

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

Annotations already declare idempotentHint=true and destructiveHint=true, but the description earns credit by making idempotency concrete: repeating with the same winning receipt succeeds, while a stale/expired receipt is a conflict. "Completion does not reclaim the lifetime job allowance" is a non-obvious side effect found nowhere in the structured fields. It leaves the destructiveHint unexplained — it never says what, if anything, is destroyed or consumed by completing the job.

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 primary action, then the idempotency rule, then the failure case, then the side effect. No filler and no restatement of the title.

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

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

An output schema exists, so return values need not be described, and the description covers the main behavioral risks for a mutation: idempotent retry, conflict on stale receipt, and allowance accounting. What remains is the meaning of the destructive annotation and whether completion attests any result payload — minor gaps for a well-annotated 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%, so all four parameters are already documented, including the receipt's staleness rule. The description only reinforces the receipt/token roles at a high level and adds no format, source, or edge-case detail the schema lacks — 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?

"Mark a claimed job completed" gives a specific verb and resource, and the mention of worker token plus current receipt pins down exactly which operation in the claim/renew/release/acknowledge family this is. It stops short of naming the closest siblings (release_agent_queue_job, renew_agent_queue_job) outright, so disambiguation is inferred from terminology rather than stated.

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

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

Usage context is implied by "a claimed job" and "the current claim" — the agent can infer it must call claim_agent_queue_job first and hold a valid receipt. There is no explicit when-not guidance and no named alternative for the case where the agent wants to give the job back or extend the claim.

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

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

Annotations are sparse (no idempotency flags), and the description compensates by disclosing the success result (owner + monotonic fencing token), the possible outcomes for later callers, and the fact that contention is normal. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

Four short sentences, front-loaded with the core purpose, followed by outcome/contention guidance and namespace advice. Every sentence earns its place and there is no filler.

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

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

Description covers purpose, outcomes, contention expectations, key safety, and authentication. Return-value details are already handled by the output schema, so nothing needed for a correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline applies; the description's namespace/key advice mainly restates the schema's guidance rather than adding new per-parameter semantics. No additional value is added for fingerprint or ttl_seconds beyond what the schema already provides.

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

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

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

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

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

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

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

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

Annotations only declare that this is a non-read-only, non-destructive, non-idempotent write. The description goes well beyond them: notes persist until collection expiry, consumption counts against a 500-note lifetime limit even after deletion, a shared 60/min and 1000/day per-IP rate limit applies, and refusals may carry Retry-After. It also adds a data-handling warning about secrets and personal data.

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 batch size and token requirement are front-loaded, and each following sentence carries a concrete constraint. The closing 'No API key, no account and no sign up' is onboarding framing rather than invocation guidance, which is the only real 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, the description covers limits, persistence, and failure signalling well. It does not say what a successful call returns (assigned note identifiers, accepted versus rejected keys, remaining quota), which matters for a batch call where partial acceptance is possible.

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 would be 3, but the schema types the notes array only as generic objects while the description supplies the real item contract: a text field of 1-2000 characters and an optional key limited to 64 characters from a stated charset. That is genuine semantics the structured schema does not carry.

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 ('Add 1 to 32 notes') and states the scope of the write. An agent can tell this is the write path for a semantic search collection as opposed to query_semantic_search or delete_semantic_search_note, though it never names those 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?

Practical constraints (1-32 notes, 2000-character text, 500-note lifetime cap, 60/min and 1000/day limits) give a strong sense of when this tool applies, but there is no explicit routing guidance such as when to use this versus create_semantic_search or delete_semantic_search_note, and no statement of prerequisites beyond the token.

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, it discloses the failure mode (a 409 that carries the real current state), the nonce-based replay behavior returning `repeated: true`, and that no credentials are required. `idempotentHint: false` remains consistent because a same-nonce replay returns a distinguishable response rather than a plain repeat. It omits the shape of a successful response beyond the transition name.

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 tight sentences with the core action front-loaded and preconditions before error behavior. The closing line about no API key or sign-up is slightly promotional, though it does convey the auth requirement.

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 full annotation coverage, full schema coverage, and no output schema, this covers preconditions, conflicts, and retry semantics well. The remaining gap is that the set of allowed transitions and the success payload are never described, so an agent learns the state machine only by hitting errors.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the coupling between `from`, the allowed-transition check, and the 409 payload, plus how `nonce` interacts with replays. That adds real meaning not present in the one-line schema descriptions.

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

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

The description opens with a specific verb and resource ("Move a handoff to the state named in to") and frames the operation as an optimistic-concurrency state transition, which is clearly distinct from create_agent_handoff or read_agent_handoff by nature. It never names a sibling tool explicitly, so it falls short of the top mark for 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 defines the precondition for a valid call (the handoff must be exactly in `from` and the transition must be allowed) and describes the retry path, so usage is implied well enough to attempt a call. It never states when to prefer this over read_agent_handoff or how to discover the set of allowed transitions, which is the main practical 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?

The annotations already declare destructiveHint=true and idempotentHint=true, so 'Repeating a burn is safe' largely restates them. What the description adds beyond the structured fields is the authentication profile ('No API key, no account') and the precise boundary of what is destroyed (pending ciphertext only; already-revealed secrets are unaffected). That last point is the key behavioral fact an agent needs before calling a destructive 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 destructive action and its consequence are front-loaded in the first sentence, and the remaining sentences each add a distinct fact (idempotency, scope limit, no-auth). The trailing marketing-style phrasing 'no account and no sign up' is slightly redundant with 'No API key' but still conveys auth requirements.

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

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

For a two-parameter destructive tool with full annotation and schema coverage and no output schema, the description covers the essential facts: what is removed, that repeats are harmless, that revealed secrets are out of reach, and that no credentials are needed. It does not describe the response or what happens if the token is invalid, but annotations and schema carry most of that weight.

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 both parameters carry regex patterns and semantic notes ('not a credential', 'cannot reveal'). The description only echoes that the receipt token is the means of burning, adding no format or failure-mode detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'Permanently remove any pending ciphertext'. It also scopes the operation to pending ciphertext, which implicitly separates it from reveal_one_time_secret. It never names a sibling tool explicitly, so it stops short of a 5.

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

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

'Burning cannot recover or revoke ciphertext already revealed' tells the agent the operation only applies to pending secrets, and 'Repeating a burn is safe' covers repeat calls. However, it never points to reveal_one_time_secret or read_one_time_secret_receipt as the alternative when the agent actually wants to read the secret, which is the most likely competing intent.

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 destructive=true, idempotent=true and readOnly=false, so the safety profile is covered. The description adds real value on top: it discloses the terminal effect ('Nothing further starts') and the exact failure mode for a repeat call (409 returning the real status), which an agent cannot infer from the annotations alone.

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 credential, then the terminal effect, then the error semantics. The closing 'No API key, no account and no sign up' is more onboarding copy than tool guidance but is at least short and placed last.

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 burden and does address the failure path (409 with the real status). It is silent on the success response body, but for a two-parameter terminal action with full schema coverage that is a minor gap rather than a blocking one.

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 are documented as the control_token and run_id returned at creation. The description only echoes the token requirement ('with its control token') and adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('End a run') plus the required credential ('with its control token'), which separates it from read_agent_run, create_agent_run and complete_agent_run_step among the siblings. It stops short of naming the sibling it displaces, so it is clear but not maximally 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?

Usage is implied rather than stated: you call it to terminate a run, and the note that a cancel after the end answers 409 tells the agent it should not be used to poll status. No explicit when-not or named alternative (e.g. complete_agent_run_step for normal finishing) is given.

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, so the safety profile is covered structurally. The description adds the useful precondition for the not-yet-finished state and an auth note, but never says what actually happens to the cancelled schedule or to a delivery already in flight.

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 first two sentences are tight and front-loaded with the operation and its precondition. The trailing 'No API key, no account and no sign up' is marketing filler that does not help an agent invoke the tool and dilutes an otherwise clean definition.

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

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

For a single-parameter destructive operation with no output schema and rich annotations, the definition covers the essential precondition. A line describing the resulting state of the schedule (removed, marked cancelled, or delivery suppressed) would close the remaining gap.

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

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

The sole parameter has 100% schema description coverage, including a UUID pattern and a pointer to schedule_webhook as its source, so the schema does the work. The description adds nothing about the parameter, which is the expected baseline when coverage is 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?

States a specific verb and resource ('Cancel a scheduled webhook') plus a scope qualifier ('that has not finished'), so the agent knows exactly what operation is performed. It does not explicitly contrast with siblings such as read_webhook_schedule or schedule_webhook, so differentiation is left to the 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?

Gives both a use condition (schedule has not finished) and an explicit exclusion (an already-ended job cannot be cancelled), which is stronger than most definitions provide. It stops short of naming an alternative such as read_webhook_schedule to verify status before cancelling.

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 it discloses several non-obvious traits: an immediate null return when the queue is empty, a new secret receipt embedded in the returned job, at-least-once delivery requiring idempotent worker side effects, a five-failed-claim failure threshold, and the fact that the server never executes the job. These are exactly the behaviors an agent must know before polling in a loop.

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?

Five short sentences, front-loaded with the purpose, then the return shape, then the timeout rule, then delivery semantics and failure threshold. No filler and nothing that could be dropped without losing an operational 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?

For a claim/poll tool with an output schema present, the description covers the empty-result case, receipt issuance, visibility window, redelivery, and failure threshold — everything an agent needs to call it correctly and handle the response. No material gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including patterns and min/max. The description's visibility-timeout sentence (default 60, range 30-900) restates what the schema declares rather than adding new meaning, so it sits at 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 and resource ("Claim the next pending job") plus the credential used ("worker token"), which cleanly separates it from siblings like read_agent_queue_job, ack_agent_queue_job, renew_agent_queue_job and release_agent_queue_job. An agent can identify the operation 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?

The description gives clear operational context for when to call it (poll for the next pending job) and what to do when the result is empty (job:null means no work). It does not explicitly name alternatives or exclusions, e.g. when to prefer read_agent_queue_job over claiming, so it stops short of full routing guidance.

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

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

Beyond the annotations it discloses that the call triggers the next step in the same request, explains the idempotent retry semantics (matching idempotentHint=true), describes the 409 response code, and states no API key or account is needed. These are the behaviors an agent needs and could not infer from the structured hints alone.

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?

It is dense and front-loads the version scope and purpose, with every sentence carrying operational content. It reads as one long packed paragraph rather than structured points, which slightly hurts scanability.

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, the description covers prerequisites, side effects, retries, and error codes, which is most of what is needed. It leaves terms like submission_status and verifying unexplained and does not describe the success response shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: token is the worker_token and receipt comes from claim_agent_queue_job. It does not add detail on run_id/step_id/result beyond the schema, keeping it at a 4.

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?

It states a specific verb (hand in the result) plus the exact resource (a delegated step of an agent run) and pins the scope (external-worker version 1 only). It also distinguishes itself from a sibling, telling the agent the run completes the job itself so no ack_agent_queue_job call is needed.

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 the precondition (use the receipt from claim_agent_queue_job), the exclusion (send no ack), the retry protocol (repeat the same request after a lost answer or while submission_status says verifying), and error handling (a 409 carries a code saying what to do). That covers when to use, when not to, and what to do on failure.

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 declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds two real behavioral facts: 'The answer says what the input was read as' (disambiguating seconds vs milliseconds interpretation) and that no auth/signup is needed. It does not state the default zone when offset is omitted, which is the main unresolved behavior.

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

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

Front-loaded with the core transformation and output formats in the first sentence, then offset semantics and interpretation disclosure. The trailing 'No API key, no account and no sign up' is promotional filler that does not help the agent invoke the tool, costing some conciseness.

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

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

For a two-parameter, non-destructive utility with no output schema, the description supplies enough: accepted input types, output formats, and offset meaning. The only meaningful omission is the default offset behavior and any note on how ambiguous numeric values (e.g. 10-digit vs 13-digit) are resolved beyond the vague reassurance that the answer reports the interpretation.

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 baseline is 3, but the description genuinely adds meaning: it tells the agent that value may be in seconds OR milliseconds (the schema only says 'A Unix timestamp') and that offset controls the zone of the returned answer rather than merely formatting. That is semantic value 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 (Convert) and enumerates both the accepted input shapes (Unix seconds/milliseconds, date-time text) and the exact output forms (Unix timestamp, ISO 8601, RFC 2822, UTC). This clearly separates it from siblings like get_current_time, list_timezones and time_formats, which do not perform input-to-multi-format conversion.

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

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

Usage is implied by the input/output enumeration — an agent can infer this is the tool for normalizing a known time value into other representations. However, there is no explicit when-to-use guidance and no routing advice against get_current_time or time_formats, so the selection logic must be inferred.

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 past the annotations: 24-hour lifetime, 100-per-IP-per-UTC-day creation cap, one-shot owner_token/receiver_token issuance, per-transition notify_url signals, and the forward-only state machine rule. The 'not idempotent' note corroborates idempotentHint=false rather than contradicting it.

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

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

One dense paragraph, front-loaded with what is created and how long it lives, then tokens, notifications, and limits. Mostly earned sentences, though the final 'No API key, no account and no sign up' clause is a run-on tail that 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?

For a six-parameter, non-idempotent creation tool with no output schema, the description covers lifetime, tokens returned, rate limit, and notification behavior — everything needed to call it safely. Nested 'transitions' semantics are also explained adequately.

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 already 100%, so the baseline is 3, but the description adds the 16 KiB payload ceiling and the default state list including which states are final — details the schema only hints at. The explanation that states/final/transitions may declare an alternate machine also clarifies interaction between the three 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 ('Create one piece of work to pass to another agent') plus the concrete shape of the artifact ('a small state machine that lives 24 hours'). This clearly separates it from sibling read_agent_handoff and advance_agent_handoff, which operate on existing handoffs.

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 scenario well (handing work to another agent, distributing receiver vs owner tokens) and warns 'not idempotent', which steers the agent away from blind retries. It does not explicitly contrast with adjacent creation tools like create_agent_inbox or create_agent_queue, so the agent must infer the choice.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is exceptionally transparent about behavioral details beyond annotations: the fixed 24-hour non-extendable lifetime, single issuance of read/write/worker bearer tokens, secret-sharing guidance, job and payload limits, claim limits, per-IP queue limits, non-execution of jobs, and lack of account/API key requirements. This fully compensates for the sparse annotations.

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

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

The description is front-loaded with the core purpose and then efficiently packs the most decision-relevant constraints, token handling, quotas, and execution semantics. No sentence is filler; each adds operational guidance an agent would need.

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

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

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

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

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

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

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

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

The description opens with a specific verb and resource: 'Create a small temporary pull queue for cooperating agents.' It clearly identifies this as a queue-creation tool, distinct in nature from sibling inbox, wake, webhook, and heartbeat tools, and it does so without simply restating the tool name.

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

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

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

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

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

Annotations only indicate readOnly=false, openWorldHint=true, idempotent=false, and destructive=false. The description adds valuable behavioral context beyond those: bodies and human answers are readable by anyone with the task URL, secrets should not be sent, and task lifetime ranges from 60 seconds to 24 hours. Nothing in the description contradicts the annotations.

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

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

The description is compact and front-loaded: it defines what the tool does, specifies when to use it, states the duration limit, and includes an important security caveat. Every sentence contributes useful information with no redundancy or filler.

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

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

The input schema and output schema already cover parameter and return details, so the description can focus on lifecycle, security, and intent, which it does. It adequately covers the usage scenario and important caveats, though it could have named sibling tools like create_human_approval or create_webhook_capture to further guide selection.

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

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

Schema description coverage is 100%, and each parameter already has a clear description in the schema. The tool description adds no additional parameter-level meaning beyond grouping the event types, but with full schema coverage the baseline of 3 is appropriate.

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

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

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

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

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

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

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

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

Goes well beyond the annotations: names are assigned not chosen, formatted as aisense-<slug>.53for24h.com, the dns_token is returned once and never again, expiry is 24h with no extension, no tunnel/hosting/cert/HTTPS, and shared certificate quota on a non-PSL zone. This is exactly the behavior a caller needs and cannot infer from readOnlyHint/destructiveHint/idempotentHint; the only mild mismatch is that a public DNS registration arguably reads as open-world while openWorldHint is 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?

Front-loaded with the core action and lifespan, then layered constraints in short, dense sentences. Nearly every sentence carries a distinct constraint; the certificate-quota/PSL sentence is the most marginal but still a real operational 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?

An output schema exists, yet the description still flags the single most important return value (dns_token, shown once) and ties it to the update/delete siblings. Combined with the 24h lifetime and non-DNS limitations, an agent has everything needed to call this correctly and safely.

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%, with both ip and ttl already documented in-schema, including the IPv4/IPv6 restriction and the single-value enum. The description reinforces that the hostname is never caller-chosen, but adds no new per-parameter syntax or format guidance, so the schema does the heavy lifting.

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

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

States a specific verb and resource ('Point a public hostname at an address you already control') plus the scope of the operation (24 hours), which immediately separates it from siblings like create_qr_code, shorten_url, or acquire_lease. The agent can tell what is created and how long it lives without opening the schema.

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

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

Gives concrete when-to-use triggers (webhook target typed by a human, a staging box whose address moves, a name two agents must share) and an explicit prohibition ('Do not put a login on one'). It lacks an explicit contrast against a named alternative, but the conditions for use are 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?

Adds substantial context beyond annotations: the 24-hour maximum lifetime and that pings cannot extend it, that a miss fires a webhook or wakes a task exactly once, that the returned ID/URLs are bearer secrets, and that no authentication is required. These are important operational and safety facts the annotations do not convey.

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

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

Front-loads the core purpose in the first sentence and each subsequent sentence carries distinct information (timing, dispatch, lifetime cap, secret handling). It is slightly longer than strictly needed but has 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?

With an output schema present, return details need not be explained, yet the description still flags the security-sensitive nature of returned values. For a nested-object, three-required-parameter mutation tool, nothing an agent needs before calling 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 baseline is 3. The description echoes the interval-plus-grace timing rule and the on-miss dispatch behavior, but adds little syntax or constraints (port, host, size limits) beyond what the schema already documents in detail.

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 a deadline monitor') plus the objects it monitors (job, device, agent). It is clearly distinguishable from siblings ping_heartbeat and read_heartbeat, which are referenced or implied.

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 tells the caller to use ping_heartbeat before the expected interval plus grace period ends, which routes the agent to the correct companion tool. It does not, however, contrast this with alternatives like scheduled webhooks or leases, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations: 24-hour form expiry, no API key/account/login needed, notify_url delivers only a small signal and never the answers, and group results contain counts, a tally and anonymous numbered responses. These are exactly the operational facts an agent needs and none are in 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?

Six tight sentences with no filler, and the core action plus respondent-count guidance are front-loaded. The opening is slightly indirect ("Put a decision in front of...") where a direct create verb would be sharper.

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?

An output schema exists, so return shape needn't be spelled out, yet the description still characterizes group results. The one material omission is how the answers get back to the agent — there is no pointer to read_human_approval or mention of what the creation response returns.

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; the description still adds real meaning by explaining that respondents maps to separate single-use bearer links and that notify_url fires one content-free signal after the final answer, details the schema descriptions only partially 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 concrete action and resource in plain terms: putting a decision in front of 1-20 people via bearer form links. An agent can tell this creates approval requests, but the description never names the closely related sibling read_human_approval, so it does not fully disambiguate create-vs-retrieve in this family.

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?

"Use one respondent for a normal approval, or several when every invited person should answer through a separate bearer form link" gives clear guidance for parameter selection, but there is no guidance on when to choose this tool over alternatives (e.g. create_one_time_secret or decide) or how results are subsequently fetched.

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?

Goes well beyond the annotations, which only declare the write/non-idempotent/closed-world profile. The description adds TTL (24 hours), the one-time return of read and receipt tokens, the 100-per-IP-per-UTC-day rate limit, the 16384-byte pre-encryption plaintext cap, and a concrete security warning about client logging of arguments and bearer tokens.

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 verb and TTL, then layers the security instruction, the return-value note, the size limit, the rate limit and the auth model in short declarative sentences. No filler; every clause carries an operational constraint.

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

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

There is no output schema, and the description compensates by stating that separate read and receipt tokens are returned exactly once. Combined with the rate limit, size cap, and no-account model, an agent has everything needed to call this correctly on the first attempt.

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 nonce/version/algorithm/ciphertext fields are already documented. The description still contributes meaning the schema does not: the 16384-byte plaintext limit before encryption and the requirement that the key never accompanies the envelope, both of which constrain how the parameters must be produced.

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 ('Store an already encrypted AES-256-GCM envelope') plus a hard scope limit ('at most 24 hours'), which naturally separates it from reveal/burn/receipt siblings. It never names those siblings explicitly, so an agent must infer the routing from the verb alone.

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 operational prerequisites: 'Encrypt locally first. Never send plaintext or the decryption key to MCP, chat or this API.' It also flags the non-idempotent, rate-limited, unauthenticated nature of creation. What's missing is explicit direction to the companion tools (reveal_one_time_secret, read_one_time_secret_receipt, burn_one_time_secret) for the retrieval half of the flow.

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 closed-world scope, so the safety profile is covered. The description adds genuinely new context: the output is a PNG image, it uses error correction level H, and no authentication is required. It stops short of stating size limits or how the image bytes are returned.

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 core purpose, then output format, then access requirements. Nothing is redundant and every sentence contributes.

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

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

For a single-parameter tool with no output schema, the description covers purpose, output type and authentication, which is enough to call it correctly. It could say more about what exactly is returned (binary vs base64) and any content-size limits, but the essentials are present.

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 one parameter and 100% schema description coverage, the schema already documents the 2000-character text/URL input. The description's "text or URL" phrasing reinforces the accepted values but adds no syntax or format detail 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 gives a specific verb and resource ("Make a QR code") plus the input domain (text or URL) and output format (PNG, EC level H). It is clearly distinct from the decoding sibling read_qr_code, though it never names that sibling explicitly.

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

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

Usage is only implied: the tool generates and read_qr_code presumably decodes. There is no explicit when-to-use / when-not-to-use statement or named alternative. The "no API key, no account, no sign up" line speaks to setup, not 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?

Goes well past the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the ephemerality (24h, non-extensible), the one-time secret return of separate read and write bearer tokens with a secrecy/share-only-needed warning, hard quotas, and that no API key or account is required. The one-time credential disclosure is exactly the kind of irreversible behavior an agent must know about.

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 purpose, then lifetime, model, return values and limits in a compact sequence. The closing 'No API key, no account and no sign up' is borderline promotional but still carries an auth-relevant fact, so only minor tightness is lost.

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 only one optional parameter, no output schema and non-destructive annotations, the description covers everything an agent needs: what is created, how long it lives, what comes back (collection_id plus read/write tokens), the secrecy obligation, and the quotas that constrain reuse.

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 enum and default are already documented; the description adds real meaning by saying the chosen model 'stays fixed for the collection', i.e. the parameter is a permanent commitment rather than a per-call setting.

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 a collection of short notes') plus the defining capability ('agents search by meaning, across wording and between languages'), which cleanly separates it from siblings like query_semantic_search, add_semantic_search_notes 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 the operative context an agent needs before calling: fixed 24-hour lifetime that cannot be extended, a model choice locked for the collection's life, a 500-note ceiling and a 20-collections-per-IP daily cap. It does not explicitly name the follow-up tool (add_semantic_search_notes) or state when not to use it, so it stops short of full routing guidance.

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

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

The annotations only declare the generic profile (not read-only, open-world, non-idempotent, non-destructive), while the description adds the operationally important facts: no API key or account needed, the pending capture is stored before the call returns, and the write is public so secrets/credentials/personal data must not be sent. The notify_url delivery contract — one signal with a result URL, not the captured payload — is behavior an agent could not infer from 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?

Front-loaded with the core definition, then constraints and the security caveat; every sentence is doing work except the reference to 'update_url', a parameter that does not exist in this tool's schema and reads as leftover boilerplate from a sibling tool, which can send an agent looking for a nonexistent field.

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?

An output schema exists, so return values need not be explained, and timing, callback behavior, and safety are all covered. The gaps are minor but real: capture lifetime/expiry is unspecified and the description never points at read_webhook_capture as the way to fetch the recorded request.

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 optional parameter is already documented, but the description adds real meaning beyond the schema: the callback carries a result URL and explicitly does not contain the captured request, and the public-readability warning constrains what an agent should ever send. This is meaningful value over an already-complete 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 first sentence states a specific verb and resource — create a throwaway URL that records the next inbound HTTP request with headers and body — and the scope (one request only) distinguishes it from read_webhook_capture and schedule_webhook without requiring the schema. An agent can tell immediately what is produced.

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 when-to-use guidance: inspecting what a provider/form/third party actually transmits rather than trusting docs, and proving an integration fired. It does not, however, explicitly name the follow-up tool (read_webhook_capture) that retrieves the capture, nor state when not to use it versus schedule_webhook for repeated captures.

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 annotations already declare readOnlyHint=true, openWorldHint=true and idempotentHint=false, and the description adds real context beyond that: the exact upstream data sources (blockchain.info, a public Ethereum RPC node, Solana mainnet RPC), that no API key or signup is needed, and the security caveat that a generated private key is transmitted once and not stored. What it does not disclose is the shape of the result (units, precision, native vs. token balances) or failure behavior for a malformed address, which matters given there is no output schema. Note that a key-pair-generating operation sitting under readOnlyHint=true is unusual, though generating and returning a key pair does not modify server state, so this is not a 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?

Three sentences, all of which carry information, and the no-API-key line is front-loaded value. However, the opening sentence is a long run-on fragment that stacks three chains, three providers and a second operation into one clause, which hurts scannability for an agent parsing it quickly.

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 tool with no output schema, the description should at least hint at what a balance result contains (currency units, decimals, whether it reflects confirmations) and what happens on an unknown or malformed address. It covers inputs, providers and the key-handling caveat well, but leaves the return value entirely undefined.

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 enums are documented in the schema itself, including that address is 'balance only' and that new_wallet generates a key pair sent once and not stored. The description largely restates those facts (public address, generated key pair) without adding format or validity requirements. Baseline 3 is appropriate when the schema carries the semantics.

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 the concrete resource (balance of a public Bitcoin, Ethereum or Solana address) and the alternate mode (a newly generated key pair), so an agent can tell it apart from every sibling, none of which touch crypto keys or chain balances. It is a noun phrase rather than a verb-first statement and never uses the schema's operation names (balance / new_wallet), so the mapping from intent to call is slightly inferential.

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

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

There is one real usage rule: a generated private key transits the service, so it should be used only for tests and small amounts. That is a genuine when-to-use constraint, but there is no guidance on when to pick balance vs new_wallet, nor any exclusion such as chains that are unsupported or addresses that will fail validation.

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?

Well beyond the annotations, it discloses concrete limits (8 KiB JSON, 3 KiB for tev1, 4 questions, 8 choices per question), rate limits (60/min, 1000/day per IP), Retry-After on refusals, and a data-retention stance (request and answer bodies not stored; usage counters are). The explicit 'Do not send credentials or sensitive personal data' and 'No API key, no account' statements are exactly the kind of context annotations cannot carry. This is consistent with readOnlyHint=true (no mutations) and idempotentHint=false (per-IP counters accumulate).

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?

It is one long paragraph of run-on clauses with typos and some redundancy ('No API key, no account and no sign up' plus the external URL). Most sentences do carry load-bearing facts, but the limits, rule format, and privacy notes are not grouped or front-loaded, so an agent must parse the whole block.

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

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

For a nested-object tool with no output schema, it covers request shape, rule grammar, model limits, rate limits, and return behavior in model mode ('returns structured answers without an automatic action or rule trace'). The remaining gap is that the answer shape and rule-mode output are only available via the external documentation link, which an agent may not be able to fetch.

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

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

Schema coverage is 100%, so the schema already names and describes all three parameters, but the description goes further: it explains what 'state' represents ('state holds the facts'), the shape of a rule ({"if": condition, "weight": number}), and enumerates the condition operators (eq, ne, gt, gte, lt, lte, in, exists, prefix, contains, combined with any/not). That is meaning genuinely beyond the schema and offsets the vagueness of the 'questions' property description.

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

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

The description says it runs decisions over 'the existing yes_no, choice and scale rule engine' or through one of three models, so the verb+resource is clear. It does distinguish itself in spirit from other tools, but garbled/'typo'd phrasing ('Omit model or use rules', 'noul' twice, 'scale' vs 'score') blunts precision. An agent can tell what it does, but one read may not be enough.

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?

Strong internal routing: it says to omit the model or use 'rules' for the existing rule engine and to use clef/nimble/tev1 for model questions, plus that tev1 is 'smallest and fastest, tested by its maker in English only' and suits short, direct questions. What is missing is any routing against sibling tools (e.g. validate_value, match_tables), so guidance is clear within the tool but not across the toolset.

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 readOnly/idempotent/openWorld annotations, the description discloses that the API performs processing, the decoded result is not stored, the stored input retains its original 24-hour lifetime, no max_downloads limit is allowed on the storage object, and no API key or account is required. That is meaningful operational context an agent could not infer from 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 core statement is front-loaded in the first sentence, with size, lifetime and auth details following in a logical order. A few clauses are peppered in as afterthoughts ("No API key, no account and no sign up" repeated in spirit by the earlier REST mention), which slightly dilutes density but does not obscure the call contract.

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

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

There is no output schema, and the description compensates by naming the return fields (data_base64, byte_length, text) and the UTF-8 condition for text. Combined with the size, duration, sample-rate and storage-lifetime constraints, an agent has everything needed to call this correctly on the first attempt.

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 already 100% and the mode enum is documented in-schema, so the baseline is 3. The description adds real constraints on storage_id (must be an ordinary 24-hour file with no max_downloads limit, sourced from store_file or REST /storage) and reinforces the auto-vs-explicit band choice, pushing it above 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?

Opens with a specific verb and resource: "Recover one checksum-verified AI SENSE audio message... from a PCM16 WAV recording," and names the format variants (audio-v2 / v1). It also preempts confusion with a sibling capability by stating "This is data-over-sound decoding, not speech transcription," which sharply separates it from any transcription or generic read tool.

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?

Preconditions are concrete: 44100/48000 Hz, mono or stereo, at most 40 seconds, WAV of at most 4 MiB, and the file must be uploaded first through REST Storage because "WAV recordings exceed the inline MCP request limit." It doesn't explicitly route the agent to encode_audio for the inverse operation, so the alternative-tool mapping is 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?

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?

The annotations already declare destructiveHint=true and idempotentHint=true, so safety is partly covered. The description still adds real value beyond them: the text and vector are removed immediately, and the 500-note lifetime quota slot is permanently consumed — a non-obvious consequence an agent would otherwise not anticipate. It omits error behavior for a wrong token or unknown note_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?

Four very short sentences, front-loaded with the action and credential, then the destructive effect, then the quota caveat. Nothing is redundant and every sentence 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?

For a 3-parameter destructive tool with no output schema but rich annotations, the description covers credential requirements, effect scope and the irreversible quota cost. Only return-value shape and failure handling are absent, which are minor given the annotation coverage.

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 of the three parameters is documented in the schema, including where note_id and write_token come from and the hex patterns. The description only restates that the write token is needed, adding no format or sourcing detail beyond what the schema supplies, so baseline 3 applies.

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

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

Names a specific verb and resource ('Delete one note') scoped to a semantic search collection, with the required credential stated up front. An agent can distinguish it from add_semantic_search_notes or query_semantic_search by name and phrasing, though the description itself never references those 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?

Usage is implied: it is the removal counterpart to adding notes and requires the write token. However, there is no explicit statement of when to delete versus re-create a collection, and no exclusion or prerequisite guidance (e.g. what to do if the note was already deleted).

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 closed-world, so safety is covered; the description still adds substantive behavior the annotations cannot express — the encoding is unencrypted, nothing is persisted, no API key or account is required, and high/ultrasound modes are experimental and device-dependent. The 1–128 byte bound and the four-tone/Reed-Solomon/CRC design give the agent realistic expectations about robustness.

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?

Core capability is front-loaded in the first clause, and each following sentence adds a distinct fact (encodings, modes, workflow, privacy). The closing 'Nothing is stored. No API key, no account and no sign up.' is partially redundant with openWorldHint=false and could be compressed into one clause.

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

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

With no output schema, the description must carry the return shape, and it does name the artifact (PCM16 WAV audio block) — though it never says whether that comes back as raw bytes, base64, or a reference, which matters for a binary payload. Everything else an agent needs to call it correctly (size bounds, mode tradeoffs, unencrypted nature, no storage) is present.

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 earns more by adding meaning the enum descriptions lack: concrete frequency ranges for high (14.0–16.2 kHz) and ultrasound (18.0–20.2 kHz), the warning that both can still be audible, and the UTF-8-vs-base64 rule restated with the byte-limit rationale. It does not explain the relationship between the 172-char maxLength and the 128-byte limit, which is the one place a param needs more help.

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 ('Turn 1 to 128 bytes into a PCM16 WAV audio block') plus the named format (AI SENSE audio-v2), which cleanly separates it from the sibling decode_audio. An agent can identify the transform, its input domain, and its output artifact without opening the schema.

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

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

Gives explicit operational context: 'Play the audio near a listening device, then decode its recording,' which implies pairing with the decode_audio sibling, and explains when to pick high/ultrasound versus the audible default. It stops short of naming the sibling tool or stating exclusion conditions (e.g., why not use encode_data), so it is clear but not fully routing-grade.

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/idempotent/closed-world, so the safety profile is covered. The description still adds real behavioral context beyond them: the conditional return field (decoded_text for UTF-8, decoded_base64 for binary), a 64 KiB ceiling for Base58, no-padding base64url, RFC 3986 percent-encoding with space as %20, and the absence of auth requirements. A 5 would require stating what encode itself returns and how overlength input fails.

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 front-load the operation and format set, then move to the return-value and format-specific caveats, which is the right ordering. The trailing 'No API key, no account and no sign up' is slightly redundant with a public read-only tool, but it still conveys that no credentials are needed.

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 takes on the burden of explaining return values and does so for decode. The remaining gap is encode's return shape, which is left unstated, and there is an unexplained tension between the schema's 250000-character data limit and the description's 64 KiB Base58 cap.

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

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

Schema coverage is 100%, so the baseline is 3 and the description only earns credit for genuinely new semantics. It supplies them for format nuances not fully in the schema (the Bitcoin alphabet size cap, unpadded base64url, %20 for space) and clarifies that decode yields either text or bytes. Some of this does restate the enum descriptions, keeping it off 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?

The description states specific verbs (encode/decode) and enumerates the exact resource set (Base64, Base64url, Base32, Base58, hex, URL percent-encoding, HTML entities), so an agent knows precisely what family of transformations this covers. It never names a sibling to delimit against, so an agent must infer on its own that hashing belongs to hash_data and markdown conversion to 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 only implied: the encode/decode split is described, and the format list tells the agent which transformations are in scope. There is no explicit when-to-use versus alternatives statement, nor any exclusion such as 'for checksums use hash_data' or 'for JWT payloads use jwt_token', both of which are present as 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?

With idempotentHint=true already declared, the description goes well beyond it by spelling out the exact idempotency contract: same key plus same payload returns the original job, while a changed payload for that key is a conflict. It also discloses the 16 KiB encoded-size cap, the 100-job lifetime quota that counts completed and failed jobs, and a no-secrets/no-PII constraint - all operational facts the annotations cannot express.

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

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

Four short sentences, front-loaded with the action and credential, then the idempotency rule, then limits. Dense and mostly waste-free, though the opening clause overlaps with what the schema already says about write_token and job_key.

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?

An output schema exists, so return values need no explanation, and the description covers the failure modes an agent actually needs: conflict on changed payload, size cap, and lifetime quota. The remaining gap is minor - nothing about what a conflict error surfaces or whether enqueueing is allowed once the 100-job limit is hit.

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 all four parameters are already documented with patterns and meanings, making 3 the baseline. The description restates the write-token role and the stable job_key concept and adds the encoded-size framing, but contributes little meaning the schema does not already carry.

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 and resource ('Add a JSON job') plus the required credentials, which is clearly distinct from the claim/ack/read siblings in this queue family. It stops short of naming a sibling tool by name, but the enqueue-vs-process distinction is unmistakable from the verb.

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

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

Usage is implied by the idempotency and quota rules, which tell an agent this is the write path for creating jobs. However, there is no explicit 'use this before claim_agent_queue_job' framing, no statement that the queue must already exist (that hint lives only in the queue_id schema description), and no when-not guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context: no API key, account, or sign up is required, and passphrase output comes with entropy in bits. It does not state whether the randomness is cryptographically secure, which matters for the password and passphrase modes.

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?

Everything is packed into one sentence, but it is front-loaded with the primary capability and the kind/parameter pairings are easy to scan. The parenthetical style and the trailing 'No API key, no account and no sign up' fragment are slightly awkward yet each 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 carries the burden of explaining returns, and it does so partially by naming output formats (#rrggbb) and noting passphrase entropy in bits. It does not describe the response shape for number, color, guid, or password, nor what happens if from exceeds to, leaving a modest gap for a five-mode 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%, so the schema already defines every parameter, including ranges and enum values. The description's contribution is the documented defaults (1 to 6, 12, 4), which the schema does not state, but it adds no syntax or constraint detail beyond that.

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 (generate) and enumerates the five exact resources it produces: integer number, #rrggbb color, GUID, password, and passphrase. It also explicitly names the sibling it should not be confused with ('UUIDs come from generate_uuid'), so an agent can distinguish it from nearby tools 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?

Each kind is paired with its applicable parameters and defaults (number 1 to 6, password length 12, passphrase 4 groups), which is effectively when-to-use guidance per mode. The one alternative, generate_uuid, is named explicitly. The only gap is that the description offers a 'guid' kind while also redirecting UUIDs to generate_uuid, leaving the agent unsure which to pick for a UUID-looking value.

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 read-only and closed-world, and the description adds genuinely new behavior: no parameters, a single lowercase hyphenated return value, no auth/key/signup required, and the phrase 'one random' implicitly explains why idempotentHint is false (each call yields a different value). The missing piece is any statement that successive calls will never return the same value.

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 usage rationale, then return shape. The final sentence 'No API key, no account and no sign up' is partially marketing cadence and repeats the auth point three ways, which is the one wasteful stretch.

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 utility with an output schema and full annotations, nothing an agent needs is missing: purpose, trigger conditions, return format, and auth posture are all present.

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 zero parameters the baseline is 4, but the description adds only 'takes no parameters,' which the empty schema already conveys. It contributes no additional parameter meaning, so it lands slightly below the no-param 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?

The description gives a precise verb and resource plus a format specifier: 'Generate one random RFC 4122 version 4 UUID.' An agent knows exactly what comes back. It does not differentiate against the sibling generate_random, which is the one nearby tool an agent could plausibly confuse it with.

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 when to use it with three concrete motivating cases (idempotency key, correlation id, filename) and contrasts it with the failing alternative of hand-rolling a string. It stops short of naming an explicit alternative tool or a when-not condition, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, openWorld=false), so the description's contribution is the return format and the no-API-key/no-account note, which is useful operational context. Note a mild tension: the description emphasizes the 'actual present moment', which varies per call, while idempotentHint is set true — the description does not assert repeatability, so this is an annotation accuracy issue rather than a description 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?

The purpose is front-loaded and the rationale follows logically. The closing 'No API key, no account and no sign up' is three phrasings of one point and could be compressed to a single clause without loss.

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

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

For a one-parameter, zero-required read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what it returns, the timezone format and default, and when to reach for it instead of guessing. 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?

With 100% schema coverage on a single optional parameter, the schema already documents IANA names, UTC offsets, and the UTC default. The description restates the same facts ('IANA name or a fixed UTC offset and defaults to UTC') without adding examples or edge-case 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 names a specific verb and resource ('Get the true current date and time') and states the return shape (ISO 8601 string and Unix timestamp) plus the timezone scope. It is clearly separable from siblings like convert_timestamp, list_timezones, and time_formats, which do not return the present moment.

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 concrete triggers ('stamping a record, computing an age or a deadline, deciding whether something has expired') and explains the failure mode it prevents (a model guessing a date from training data). It does not explicitly contrast with convert_timestamp or time_formats, so the routing is implied rather than spelled out.

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 past the annotations, which only say readOnly/idempotent/closed-world. It discloses output encoding per algorithm (hex, integer for crc32, self-describing salted string for password hashes), a hard rate limit of 200 calls/day for argon2id/bcrypt/scrypt, and that no API key or account is needed. The salted self-describing output note usefully warns that password-hash results are non-deterministic across calls.

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 verb and the algorithm set, then layers cost/rate-limit/legacy caveats — no filler sentences. It is a single dense run-on, and re-enumerating all thirteen algorithms is partly redundant with the enum, but every other clause carries a distinct decision-relevant 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 only two parameters, no output schema, and annotations covering safety, the description is nearly complete: it explains return encodings and quota behavior that the schema cannot express. The only shortfalls are the undocumented input size ceiling and no pointer to verify_hash for the inverse operation.

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 baseline is 3 and the schema already documents the enum and the 200-call limit. The description still adds real meaning beyond the schema by mapping algorithm families to purposes and stating the output shape each returns, though it repeats the salt/rate-limit text verbatim and never mentions the 250,000-character input cap.

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?

"Hash text with MD5, SHA-1, ... BLAKE3" states a specific verb and resource, and the header line plus the algorithm list make it immediately distinguishable from verify_hash, which takes a digest rather than producing one. An agent knows exactly what this produces 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?

Strong algorithmic selection guidance: sha256/sha3_256/blake2b/blake3 "for integrity checks", md5/sha1 "for systems that still expect them", and password hashes flagged as "meant for test data, since a real password should be hashed where it is used" — an explicit when-not. The gap is sibling routing: verify_hash is never named, so an agent holding a digest and a candidate input is not steered away from calling this tool.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses that html_to_markdown drops scripts, styles, forms and media and returns the page title, and that markdown_to_html sanitizes raw HTML and unsafe-scheme links. It also states the no-auth requirement, which the annotations do not cover, and since there is no output schema this return-value detail is essential.

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 conversion statement, then two direction-specific sentences, then the auth note. Sentences are dense with useful detail rather than padding, though the closing 'No API key, no account and no sign up' is slightly redundant with the rest of the benefit framing.

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

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

With no output schema and only two parameters, the description carries adequate load: it explains both directions' outputs, sanitization, and auth. The main gaps are the max-length limit on input and any error/edge-case behavior (e.g., malformed HTML), which an agent might need.

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 baseline would be 3, but the description adds real meaning to the 'direction' enum by explaining the output shape and sanitization behavior of each branch (CommonMark with GFM tables, strikethrough, task lists). The 250,000-character 'data' cap is never mentioned, so size constraints remain schema-only.

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 HTML to Markdown, or Markdown to HTML') and immediately names both direction values, so an agent knows exactly which transformation it gets. It does not explicitly distinguish itself from the nearby sibling html_to_pdf, which is the one conversion tool an agent might confuse it with.

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

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

Gives concrete usage contexts: html_to_markdown is for making a fetched page read with fewer tokens, and markdown_to_html is for producing HTML that can go into a page as-is. There are no explicit when-not-to-use conditions or named alternatives, but the intended scenarios are clear.

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

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

Beyond the annotations, the description discloses that JS execution and network fetches are disabled, that only the submitted HTML is used, that output is retained for 24 hours, and that the response carries storage_id and storage_url. It also clarifies there is no API key or account requirement, which resolves practical auth questions the annotations do not address, and its 'stored file' framing is consistent with readOnlyHint=false and idempotentHint=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?

Structure is front-loaded: purpose, then the sandbox constraint, then options, then storage lifecycle. The page-size and margin enumerations duplicate the schema and the 'No API key, no account and no sign up' clause is marketing-flavored, but both are short and the remaining sentences each carry real 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 the return shape (storage_id and storage_url) and the 24-hour retention window plus the retrieval tool. For a two-parameter tool with a nested options object, nothing an agent needs to invoke it correctly or handle 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?

Schema description coverage is 100% and both parameters are already documented in the schema, including the same page-size, orientation, and margin values. The description restates those option values and adds only the '10mm'-style margin format example, which the schema also contains, so it adds little meaning beyond the structured fields.

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 first sentence states a specific verb and resource ('Render HTML to a PDF') and immediately scopes it with the sandbox constraint (JavaScript and network off), which separates it from the nearby html_markdown_convert sibling. An agent can tell exactly what output format it gets and what input limitations apply 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?

The description gives clear context for when this tool is applicable: HTML must be self-contained with inline data URLs because scripts and network access are disabled, and it names read_stored_file as the follow-up for retrieving the result. What is missing is an explicit exclusion or comparison, e.g. when to choose this over html_markdown_convert or store_file.

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 say nothing about why; the description fills that gap by disclosing that output is persisted for 24 hours and returned with storage_id and storage_url, explaining the non-read-only classification. It also removes friction by stating no API key or account is required. It could still say whether the stored artifact is retrievable/deletable or whether repeated calls create new artifacts.

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 core purpose and then the return/storage behavior, with no wasted clauses. The closing 'No API key, no account and no sign up' is slightly promotional and partially redundant with the same point made once already, but it is 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?

There is no output schema, so the description carries the return-value burden and does so by naming storage_id, storage_url, and the validate case ('reports whether it parses and where it breaks'). Combined with 100% schema coverage, an agent has enough to invoke it correctly; only the exact shape of validate's error location remains 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?

Schema description coverage is 100% and three parameters are enums, so the schema already documents data, mode, indent, and operation thoroughly. The description restates the mode and indent semantics (pretty with indent 2 or 4, compact) almost verbatim from the schema, adding no format or size guidance beyond it. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

Opens with a specific verb pair and resource ('Format or validate JSON text') and immediately splits the two operations into distinct behaviors. It does not, however, distinguish itself from nearby siblings such as json_csv_convert or validate_value, so an agent must infer the boundary from the name alone.

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 internal format-vs-validate choice clear (pretty/compact vs parse-checking), which implies when each operation applies. It gives no explicit guidance on when to pick this tool over json_csv_convert or validate_value, and no exclusions or preconditions.

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 this as non-read-only, non-idempotent, non-destructive, but the description adds substantial context the annotations cannot carry: the result is persisted for 24 hours, the response includes storage_id and storage_url, no API key or account is required, and spreadsheet_safe specifically guards against cells a spreadsheet would execute as formulas. That is a strong disclosure of side effects and auth posture for a file-producing 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?

Front-loaded with the purpose and the two modes, then layers limits, delimiter, safety, and retention in compact sentences. The final 'No API key, no account and no sign up' is somewhat promotional and repeats itself, but overall the text is dense with useful information rather than padded.

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

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

For a six-parameter conversion tool with no output schema, the description covers what is produced (result.csv / result.json), how it is returned (storage_id and storage_url), retention (24 hours), size limits, and the direction-specific parameter split. Nothing an agent needs before invoking it 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 baseline is 3; the description earns above that by explaining what spreadsheet_safe actually does (guards formula-injection-prone cells) and by clarifying the direction-dependent parameter pairing in prose. Limits like 'up to 5000 flat objects' restate schema maximums, which is why it is not 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 immediately distinguishes its two modes by name: json_to_csv takes columns and rows and stores result.csv, while csv_to_json takes data and stores result.json. An agent can tell exactly what the tool does and which direction to pick without inspecting 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?

Guidance is clear at the mode level: it names which parameters belong to which direction (columns and rows for json_to_csv, data for csv_to_json) and states the 5000 flat-object limit. It does not explicitly steer against siblings such as json_check or match_tables, so it stops short of naming alternatives, but the internal routing guidance is solid.

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 closed-world behavior, and the description adds genuinely new context: the secret is used for this call only and is not stored, and decode performs temporal claim validation (exp, nbf, iat). That non-persistence guarantee is the key behavioral fact for a tool that accepts a signing key. It does not say what a failed verification returns (error vs. a flag), which keeps 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 short sentences, front-loaded with the core purpose and then split cleanly by operation. The closing "No API key, no account and no sign up" is slightly promotional but earns its place by answering an auth prerequisite question. No filler or repetition of the title.

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

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

There is no output schema, and the description compensates by naming both return keys, jwt for encode and decoded_payload for decode. Combined with the secret non-persistence note and the claim-validation behavior, an agent has what it needs to call this correctly. The nested payload object is described only as "the claims" in both schema and description, a minor remaining gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the encode/decode enum and its meaning. The description largely restates that mapping (payload for encode, token for decode, secret as the HS256 key) rather than adding format or constraint detail beyond the schema. Baseline 3 applies when the schema carries the weight.

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 pair and resource ("Create or check an HS256 JSON Web Token") and immediately decomposes it into the two operations, encode and decode, with what each produces. No sibling in the list offers JWT handling, so there is no ambiguity about which tool to reach for.

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 routing: encode when you have a payload and want a token, decode when you have a token and want its claims, and it notes decode enforces exp, nbf and iat. It also removes a common pre-flight question by stating no API key or account is needed. It stops short of naming exclusions or an alternative tool, so it is a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds access context ('No API key, no account and no sign up'), which is genuinely useful for an agent deciding whether a call will require credentials, but it says nothing about result size, ordering, or whether offsets reflect DST for each zone at the current moment.

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 covering purpose, optional filter, and payload, followed by a short access note. The no-key/no-account clause is slightly promotional but does carry information for an agent; nothing else 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?

This is a one-optional-parameter read tool with no output schema and full annotation coverage, so the bar is low. Still, the description never indicates the shape of the result (zone names paired with offsets) or roughly how many zones come back, which matters when the filter is omitted.

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 offset parameter already carries a regex pattern and a human-readable description, so the schema does the heavy lifting. The description's example (+0530) reinforces the expected literal format but adds no semantics beyond what the schema states.

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 the returned attribute ('current UTC offsets'), and the optional narrowing to a single offset. This clearly distinguishes it from sibling tools like convert_timestamp and get_current_time, which transform or report a single point in time rather than enumerate zones.

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

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

The phrase 'optionally only those at one offset' implies the filtering use case, but there is no explicit statement of when to call this versus convert_timestamp or time_formats, and no note that the unfiltered call returns the full zone list. Usage is inferable but not 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?

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond them: geodata comes from a local GeoLite2 database (implying possible staleness/accuracy limits) and domain_ip returns only the first IPv4 address, not all records. It stops short of describing failure behavior for malformed IPs or unresolvable domains.

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 opens with the resource ('Network facts:') and then walks the four modes in the same order as the enum, so the reader maps description to schema effortlessly. The closing 'No API key, no account and no sign up' is short and earns its place as a setup constraint.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so for every mode (IP, user-agent string, country/city/coords/timezone, resolved address). For a trivial two-parameter lookup this is nearly complete; only error/empty-result behavior for invalid input is unstated.

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; the description earns an extra point by clarifying the conditional requirement that value applies only to the last two kinds, which the schema's flat 'required: kind' does not make explicit. It does not add format constraints (e.g. whether CIDR or hostnames with trailing dots are acceptable) beyond the schema's maxLength.

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?

Names a specific resource (network facts) and enumerates the four concrete outputs it can produce: client_ip, user_agent, GeoIP details for reverse_ip, and A-record resolution for domain_ip. An agent can tell exactly which mode answers which question without consulting 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?

Each kind is tied to a clear use condition ('describe this request' vs 'looks up the IPv4 address in value' vs 'resolves the domain in value'), which effectively tells the agent when to pick each mode. It also states the prerequisite that no API key, account, or sign-up is needed. It does not name any alternative sibling tool, but none of the listed siblings overlaps this function.

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 non-destructive, leaving room for the description to explain the write behavior, which it does: results are stored as JSON and retained for 24 hours, giving the agent a clear expiry horizon. It also notes no API key or account is needed, which is genuine auth context rather than repetition of the annotations. Missing is how the stored matches are retrieved or what identifiers are returned.

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 effect, followed by parameter shape. The closing 'No API key, no account and no sign up' is somewhat promotional phrasing, though it does carry usable auth information, so it is not pure 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?

With no output schema and a write-and-store behavior, the description should say what the tool returns and how the stored JSON is later accessed; it only says the matches are stored for 24 hours. Matching semantics that matter to callers (unmatched rows, multiple matches per key, key type coercion) are also absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that keys accepts multiple pairs (compound matching) and gives a concrete example of a pair object, which is more than the schema's per-field text conveys. It stops short of explaining behavior on unmatched rows, duplicate keys, or type mismatches.

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 (match), the resource (rows of two tables), the mechanism (one or more pairs of key columns, like a join), and the effect (matches stored as JSON for 24 hours). No sibling tool performs table matching, so an agent can identify it unambiguously.

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

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

Usage is implied by the 'like a join' framing and the requirement that left/right be lists of row objects, so an agent knows the shape of data this applies to. However, there is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives, and no statement of limits such as table size or row count.

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

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

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

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

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

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

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

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

With a single parameter, an existing output schema, and annotations that are all false, the description covers the essential operational facts: what the tool does, when to use it, the non-renewal caveat, and security handling. No crucial information appears to be missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by emphasizing the heartbeat_id is a 'bearer secret,' which strengthens the schema's 'secret heartbeat ID' by implying it must be protected like a credential. It does not add format details, but the schema already includes pattern.

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

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

The description opens with a specific verb and resource: 'Record a check-in for an armed heartbeat and move its next expected deadline.' It clearly distinguishes this from sibling tools like read_heartbeat (read-only) and create_heartbeat (creation), and the effect is concrete.

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

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

It gives explicit when-to-use guidance: 'Use it after successful work or from a liveness loop.' It also states a key when-not-to-use caveat: 'A ping does not extend the absolute 24 hour lifetime.' However, it does not name alternative sibling tools for comparison, so it stops short of a perfect 5.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world behavior, so the bar is lower; the description still adds real context: no API key/account required, results persist 24 hours and are keyed by storage_id enabling chained calls, and vectorize output is bounded to 1024x1024. It does not describe output payload shapes per operation, which is the remaining gap.

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?

It is a single dense paragraph but every clause carries information, grouped roughly by operation, with input mechanics and expiry placed at the end. The operation-to-parameter associations are scattered rather than front-loaded as a list, which slightly hurts scannability for a 14-parameter tool.

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 14-parameter, eight-operation tool with no output schema, the description covers supported formats, operation/parameter mapping, input sourcing, result persistence, and auth requirements. What is missing is any statement of return payloads (metadata contents, color output shape, ZIP structure), which matters given there is no 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?

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema documents (quality, lossless, threshold, width/height/fit, count, crop/name) and adds only a little meaning beyond it, notably the 1024x1024 trace bound for vectorize and the operation-to-parameter mapping (which params belong to which operation).

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) and enumerates each of the eight operations with the exact input/output formats they accept: convert JPEG/PNG/WebP/HEIC/SVG, vectorize PNG/JPEG to SVG paths, resize, compress, metadata, strip, colors, favicon. It is far more specific than the title and leaves no ambiguity about what the tool does.

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 operational routing guidance (which format each operation accepts, e.g. resize also accepts HEIC, metadata and strip also accept GIF) and explains how to supply input via image_base64 or storage_id, including chaining through returned storage_ids. There is no explicit when-not-to-use statement or pointer to an alternative, though no sibling tool overlaps with image processing, so the omission is minor.

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 useful context: no API key or account needed, the read token is required and comes from create_semantic_search, and results are capped at 10. However, it spends much of its length on scoring arithmetic rather than on operational behavior such as failure modes for an invalid or expired token.

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 and result shape are front-loaded, which is good, but the middle is a dense block of scoring rules including edge cases like '1 200 read as 1200' that cost more attention than they return for tool selection. It is one undivided paragraph with no separation between what the tool does, what it returns, and how to interpret scores.

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

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

There is no output schema, and the description fully compensates by naming the return fields (note_id, key, text, score) and explaining what the score means and its limits. Combined with annotations covering read-only and idempotent behavior, an agent has everything needed to call this correctly and interpret results.

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 all four parameters and their bounds are already documented in structured form. The description restates the limit range and default ('1 to 10 and 3 by default') and mentions the read token without adding format or provenance detail beyond what the schema provides. 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?

States a specific verb and resource ('Search the notes by meaning') and the credential it uses, so the operation is unambiguous. It does not explicitly differentiate itself from sibling read_semantic_search or add_semantic_search_notes, leaving the agent to infer that this is the ranked-retrieval path rather than the direct-read path.

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 real usage guidance in the caution that results are 'ranked suggestions, not a decision that a match exists: read the text before acting on it', which tells the agent how to treat output. It never states when to prefer this over read_semantic_search or add_semantic_search_notes, so alternative selection is left 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?

Beyond annotations, the description adds the long-poll behavior of wait_seconds (up to 25 seconds, returning on state change or handoff end) and the no-API-key/no-account auth profile, which is genuinely useful. It does not explain the apparent tension with idempotentHint=false, i.e. that repeated calls with a wait can return different states, so the behavioral picture is helpful but incomplete.

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 first sentence front-loads the returned fields well, but the second sentence is syntactically awkward ('wait_seconds, up to 25, waits for...') and the third ('No API key, no account and no sign up') reads as marketing copy rather than operational 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?

With no output schema, the description compensates by enumerating the returned fields, and it covers auth and the wait parameter. Only the interaction between read-only semantics and the non-idempotent wait behavior is left unaddressed.

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

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

Schema coverage is 100%, so the schema already documents token, handoff_id, and wait_seconds thoroughly. The description only reinforces that either token works and restates the wait_seconds semantics, 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 uses a specific verb (read) plus the resource (a handoff) and enumerates what is returned: state, payload, states, allowed transitions, and history. An agent can distinguish it from siblings like advance_agent_handoff or read_agent_run by the read-only framing, though no sibling is named explicitly.

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

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

It implies the polling use case through wait_seconds: use it to block until the state changes or the handoff ends. There is no explicit when-not guidance and no named alternative, so the agent must infer that advance_agent_handoff is the mutating counterpart on its own.

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 declare readOnlyHint, idempotentHint and closed-world behavior, so the bar is lower, yet the description adds real operational context: it will not disclose role tokens or extend the fixed expiry, and it requires the read token. It does not mention rate limits or whether counts are eventually consistent, which keeps it off 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, zero filler, with the positive scope front-loaded and the exclusions trailing. No redundant restatement of the title 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?

With an output schema present, return shape need not be explained, and annotations cover the safety profile, so the remaining needs are auth and limits, both addressed. Minor gaps around count freshness and token-scope failures are the only omissions.

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 both parameters carry descriptions pointing to create_agent_queue and create_agent_run for provenance, so the schema does the heavy lifting. The description only reinforces that the token is the read credential, which is marginal added meaning.

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 (queue metadata) and enumerates exactly what comes back: pending, claimed, completed and failed counts. The clause 'Does not list payloads' implicitly separates it from read_agent_queue_job, though no sibling is named directly.

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 establishes the precondition (a read token) and negative scope, so an agent can infer this is for status monitoring rather than job payload retrieval. However, it never states when to prefer this over read_agent_queue_job or read_agent_run, leaving the routing decision implicit.

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