Dropyour

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: the exact boundaries of each mode, the irreversible actions no mode can delegate, the account-vs-token authentication constraint, and that every change is filed. This goes well beyond what annotations alone convey.

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

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

Every sentence earns its place: purpose, default state, each mode's behavior, the bounded irreversible-action caveat, auth requirements, and logging. The structure front-loads the main purpose and then layers necessary nuance without repetition.

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

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

For a settings/mode-switching tool with two required parameters and no output schema, the description covers purpose, modes, boundaries, auth, and persistence. It does not describe the return value or success feedback, but that is a minor gap given how thoroughly the decision-relevant behavior is explained.

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

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

Schema coverage is only 50% because dropId has no description beyond its pattern. The description compensates heavily for the mode parameter by explaining all three values in concrete behavioral terms. For dropId, the description implies it identifies the specific app ('ONE of your apps'), which combined with the schema pattern is sufficient albeit brief.

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

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

The description opens with a specific action and resource: 'Declare how much you delegate to the machine on ONE of your apps.' It clearly distinguishes this tool from siblings by focusing on per-app autonomy modes, not on calls, deletes, reads, or other 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?

The description gives rich context for when to use the tool: setting one of three delegation modes for a single app, with a clear default state until delegation happens. It does not explicitly name alternatives or say 'use this instead of X', but the auth requirement ('never a management token') and the mode distinctions provide strong actionable 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 far beyond the sparse annotations: explains the request traverses the same path and guards, states there is no URL parameter by design, warns the call is a real request that counts as an invocation and can trigger writes, and discloses the hard 10-second deadline with 503 behavior. These are material behavioral traits not present in 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?

Long but organized: purpose, behavioral caveats, timeout, and routing to sibling tools are each in distinct, purposeful sentences. The ALL-CAPS phrases add emphasis but are not bloated; still, a little repetition 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 tool with no output schema and non-trivial side effects, the description is unusually complete: return fields are listed, requestId is referenced for pairing with logs, the timeout failure mode is specified, and guard behavior is explained. An agent has enough context to invoke it appropriately.

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

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

The description clarifies the core dropId/path model and explicitly rules out a URL parameter, adding meaning beyond the schema. However, with schema coverage at 33% it does not fully compensate for undocumented parameters such as managementToken or body semantics; method is left to the schema enum and default. Adequate but not complete.

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

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

States a specific verb and resource: it calls a route of the user's own drop and returns real HTTP status, headers, duration, and body. It distinguishes itself from siblings by positioning this as the way to verify a published app actually works and by referencing dropyour_logs and dropyour_schedule as related alternatives.

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

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

Gives explicit when-to-use context ('check that what you just published actually works') and names alternatives: pair with dropyour_logs to read emitted lines, use dropyour_schedule for long work. It also tells the agent that scheduled drops answering 404 is expected behavior, not a limitation.

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 destructiveHint already set to true, the description adds meaningful behavior beyond the annotation: permanence, immediate finality, and URL non-reassignment. It also clarifies a token requirement nuance. This goes beyond a bare mutation warning, though it does not describe side effects on associated data or versions.

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 two tight sentences. It opens with the core action, then adds the most critical behavioral warning, and ends with a relevant authentication detail. No sentence 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?

For a destructive tool with no output schema, the description conveys irreversibility and a key token condition, but it does not explicitly state when managementToken is required, how it is obtained, or what happens with missing authorization. The operation is simple enough that major behavior is covered, but a cautious agent would still want more guidance.

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

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

Schema coverage is 0%, so the description must compensate. It partially explains managementToken by contrasting it with the account token, but it leaves dropId's role implicit. The dropId pattern is self-evident from the tool purpose, but managementToken's exact origin or required scenarios are not fully specified.

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 delete a drop.' It also adds a distinguishing permanence fact: the URL is never reassigned. This clearly differentiates deletion from other drop lifecycle siblings like release, rollback, or replace.

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 offers useful context about authentication: 'With an account token, owned drops need no managementToken.' However, it never names alternative tools or states when deletion should be preferred over a sibling operation. 'Immediate and final' implies when to choose this tool, but the guidance is not explicit.

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

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

Beyond the annotations, the description reveals that the change takes effect on the next request with no republish, overrides the app's own declarations, and produces a named refusal (`hôte_refusé_par_le_propriétaire`) to prevent pointless code edits. It also documents the reversible behavior via `remove: true`, adding significant operational context.

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

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

The description is dense with operational facts and front-loads the core one-call, no-republish effect. The emphatic capitalization and narrative framing add some length, but nearly every clause carries decision-relevant information, so it earns a high but not perfect score.

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

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

The description covers the effect timing, override semantics, refusal naming, removal, pattern limits, host grammar, and tier restriction, giving an agent a solid basis to call the tool correctly. Minor gaps remain around the management token and behavior when exceeding the 32-pattern limit, but overall it is quite complete.

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

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

The schema covers only host and remove with descriptions; dropId and managementToken are left with no explanation. The description adds meaningful semantics for host grammar (leading `*.` wildcard, up to 32 patterns) and clarifies `remove: true`, but it does not compensate for the two undocumented parameters, so the gap remains.

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 — 'Cut a host your graduated app is calling' — and explains it as the action that refuses outbound host calls. It clearly distinguishes this from the many sibling tools by framing it as an egress override with a named refusal, not a generic network operation.

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

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

It gives an explicit trigger scenario ('the moment you read in dropyour_logs that a key is leaving toward something you did not intend') and tells the agent not to edit the app's code because the refusal is named. It also restricts use to Tier 4, but it does not explicitly name alternative tools or state when to prefer them.

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

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

Even with idempotentHint and destructiveHint annotations, the description adds substantial behavioral detail: it creates the app, migrates data, switches the URL, emails the owner, leaves the URL stable, keeps visitor data, and changes nothing on refusal. This exceeds what annotations provide and does not contradict them.

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 purpose is front-loaded and every sentence adds operational value. There is some redundancy around the URL remaining unchanged and data being preserved, but the overall density remains high and readable.

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?

Covers prerequisites, side effects, check mode, refusal behavior, and the unchanged-URL guarantee, which is enough to call the tool safely. The success return payload is not specified, but there is no output schema, and the refusal response behavior is described.

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

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

The schema covers dropId and check with 0% description coverage, so the description must compensate. It clearly explains check=true as a no-op evaluation mode, but it never explicitly defines dropId, leaving that solely to the schema's pattern and the phrase 'one of your drops.'

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—'GRADUATE one of your drops to tier 4'—and explains the distinguishing outcome: a real backend behind the SAME URL with data carried over. This separates it from sibling operations like publish, release, or rollback without needing to open those 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?

Gives clear context: requires an account token and Pro tier, and check=true provides a safe no-op verdict before committing. It does not explicitly name sibling alternatives or when-not-to-use cases, so it stops short of full 5, but usage conditions 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?

Annotations provide idempotentHint=true and destructiveHint=false, and the description complements these well by explaining the platform default (no cross-app access), same-account restriction, revoke semantics, and the limit of eight links. It clearly states it grants no identity/token/storage and that target guards still apply. Minor gap: doesn't explicitly mention whether linking is reversible beyond revoke, but 'delier revokes it' covers 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 thorough but wordy in places ('taking a right back cannot be harder than granting it' and 'it gets decided differently' are stylistic rather than informative). It front-loads the core linking purpose and keeps the not-do list near the end. It earns its length overall but could be tightened.

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

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

The description is complete for a tool of this complexity: it explains the default isolation, permissions, same-account constraint, revoke behavior, limits, and exclusions. No output schema is present, so the return format is not described, but the tool's core behavior is fully specified.

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

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

Schema coverage is 75% with meaningful descriptions for cible, action, and dropId. The description adds context about same-account verification and plain HTTP but doesn't add new details for managementToken, which is undocumented in schema. The action enum is well explained in the schema, so the description adds limited extra value.

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 (link) and resource (apps by dropId), and explicitly contrasts with what it does NOT do (no identity, token, storage). It also differentiates from siblings like dropyour_call and dropyour_egress_deny by clarifying network reachability.

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 explains the default isolation, when to use this (to allow one graduated app to call another), the same-account constraint, and implicitly contrasts with dropyour_egress_deny and dropyour_call by specifying plain HTTP and no shared storage. It also notes the eight-link limit and the revoke action.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: account-token versus anonymous scope, cross-session/channel inclusion, the LIVE status filter, and the fact that management tokens are never stored server-side. This materially improves an agent's understanding of side effects and auth requirements.

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

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

The description is three sentences with no filler. The primary action is front-loaded, followed by concise auth-dependent conditions and a security note. Every sentence adds value.

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, read-only list operation, the description is complete: it states the scope under both auth modes and the additional security trait. No output schema exists, but the tool's purpose implies a list of drops, and there are no inputs or complex behaviors an agent needs to configure.

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 and 100% schema description coverage, so there is nothing for the description to add about parameters. The baseline of 4 applies because no parameter ambiguity exists.

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: 'List your drops.' It then clarifies what set of drops is returned in each auth state, distinguishing this tool from related list/record/version siblings by specifying 'LIVE drops attached to your account' versus session-only anonymous drops.

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 the tool behaves differently: 'With an account token' lists all LIVE drops; 'Anonymous' lists only drops from the current MCP session. It does not explicitly name alternatives, but the auth-scoped behavior is enough to guide correct use.

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

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: graduated=false and empty list for non-graduated drops, degraded=true meaning unknown rather than nothing published, newest-first ordering, and the currently served version. It also clarifies the managementToken rule for owned drops.

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 dense, front-loaded sentences: action/ordering, the level 1-3 edge case, and the degraded/auth caveats. No redundant phrases 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 description explains the important return distinctions (graduated, empty list, degraded) despite having no output schema. It is nearly complete, though it could name the exact version object fields returned; the current information is sufficient for invoking 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?

With 0% schema description coverage, the description compensates for managementToken by explaining when it is unnecessary, and ties dropId to the drop/app being listed. It does not fully define every parameter, but the schema's pattern and the tool title cover the rest.

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 begins with a specific verb and resource: list published versions of a GRADUATED app, newest first, with the currently served one. It also distinguishes this from the no-history behavior of levels 1-3, so an agent can separate it from sibling tools like list or status.

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

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

It gives explicit when-not guidance: levels 1-3 have no history because replace overwrites the same key, and explains the degraded/empty-list semantics. It does not name an alternative sibling tool, so it falls just short of full alternative routing.

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

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

Beyond the readOnlyHint annotation, it discloses output limit and order (200 lines, most recent first), the inclusion criteria, the meaning of degraded: true, and warns that log content is untrusted runtime data. These are exactly the behavioral details an agent needs to interpret results safely.

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

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

The description is dense and front-loaded, with the core operation in the first sentence and scoping/security details following. The motivational 'closes the loop' sentence is somewhat non-operational, keeping it from a perfect 5.

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

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

For a tool with no output schema, it tells the agent what comes back (200 lines, most recent first, degraded flag) and how to scope to a specific call. It does not address the managementToken parameter or describe the exact response shape, leaving a small invocation ambiguity.

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

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

The description gives strong semantics for requestId (only lines emitted during that call, tied to dropyour_call), which is valuable. However, with 3 parameters and only 33% schema description coverage, appId and managementToken are left almost entirely undescribed; the prose does not compensate for those gaps.

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 verb 'Read' plus 'graduated app's own log buffer (tier 4)' states exactly what the tool does and what it returns: the last 200 lines, explicit app.log calls, and platform-captured errors. This makes it clearly distinct from sibling tools like dropyour_read_app_files or dropyour_read_content even without opening their schemas.

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 when-to-use context ('write code, see it break, read WHY, fix it') and explains the requestId filtering path from dropyour_call. It does not explicitly name alternative tools or state when not to use this one, so it misses the 5 threshold.

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

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

Annotations only say non-destructive and non-idempotent; description goes far beyond by disclosing the one-origin stable URL behavior, browser data survival, one-time token requirement, anonymous/free tier limits (5 MB, 30-day default), and private-by-default visibility. No contradiction with annotations.

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

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

Five tightly scoped sentences, each carrying load: operation, result, critical token warning, tier constraints, privacy default. No filler; warnings are front-loaded after the primary outcome.

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 publish tool with no output schema, the description explains return values (URL, token), security expectations (token shown once), availability constraints (free/anonymous), and default behavior (private, 30-day expiration). It omits explicit error/edge-case behavior, but the schema covers parameter constraints and scheduling, making it complete enough for an agent to invoke 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?

All 5 parameters have 100% schema description coverage, so the schema already documents them. The description adds relevant operational constraints (max 5 MB, 30-day default expiration, private-by-default) but these mostly restate schema field descriptions; it does not add new meaning per parameter 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?

States the exact operation ('Publish a self-contained HTML file') and the resource (Dropyour drop). It differentiates from siblings by focusing on creating a new drop and describing the result (public URL, managementToken), and by noting the token is needed for later replace/configure/delete.

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 context: this is the anonymous, keyless way to publish a new drop, with tier limits and privacy defaults. It implies the token is used for subsequent management, but does not explicitly name siblings like dropyour_replace or dropyour_delete as alternatives or state when not to use this tool.

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

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

Annotations only declare readOnlyHint=true, which the description matches, so no contradiction. The description adds substantial behavior beyond the annotation: files come from the served version not the seed, server.js is included despite never being served to visitors, large files are truncated with truncated=true and bytes reporting the real size, and binary files are reported as binary rather than mangled.

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 every sentence carries load-bearing information: mode behavior, server.js exception, replace-ordering guidance, truncation/binary semantics, and tier routing. Despite its length, there is no filler or repetition.

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

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

With no output schema, the description carries the burden of explaining return values and does so for both modes: the file list with size and server-code flag, and file content with truncation/binary handling. It also covers the security-relevant exception (server.js), the tier restriction, and the safe read profile via readOnlyHint, so an agent has everything needed to select and 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 coverage is 50% (path has a terse description, dropId has none). The description compensates for the gap by fully explaining path's two modes — omitted returns the file list with size and server-code flags; supplied returns that file's content — which adds meaning beyond the schema's "A path from the file list." dropId itself is just a conventional drop identifier shared across the tool family, so the lack of description is acceptable.

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

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

States a specific verb and resource — "Read what a GRADUATED app actually SERVES right now" — and draws the critical distinction from the seed captured before graduation. It also differentiates from the sibling dropyour_read_content by explicit tier routing, so an agent can pick the right tool without opening either 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 when-to-use: "Use this before dropyour_replace" because a graduated app is replaced WHOLE and current files are needed to avoid overwriting work. It also names the alternative and its selection condition: "Tier 4 only — at tiers 1-3 ... use dropyour_read_content."

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 provide readOnlyHint=true; the description adds significant behavioral detail: it returns asset paths but not bytes, truncates large content with truncated=true and sizeBytes, and explains when managementToken is unnecessary. This goes well beyond what annotations alone convey.

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

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

Three sentences, front-loaded with the core purpose, and every sentence carries distinct information: source HTML, asset paths and truncation, and auth behavior. No fluff or redundancy.

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

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

Without an output schema, the description still explains the main return behaviors: source HTML, asset path list, truncation flag, real size, and managementToken auth nuance. For a read-only tool with two parameters, this is complete enough for an agent to select and 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 coverage is 0%, so the description must compensate. It adds useful auth-related meaning for managementToken ('owned drops need no managementToken with an account token'), but it does not explicitly explain semantcs of dropId beyond what the schema pattern implies. The compensation is partial.

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 and resource: it reads a drop's source HTML, which is exactly what was published. It also differentiates from likely siblings by noting 'no shared-memory shim, no attribution badge,' so an agent can distinguish it from call-style 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 clear context: use this when you want the raw published source HTML and asset-path list, not the shimmed or badged execution result. It does not explicitly name alternatives or provide when-not-to-use conditions, so it stops short of a full 5.

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

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

Beyond the readOnlyHint annotation, it discloses the key behavioral branch: scope='server' with {version, data} when server memory exists, or scope='client-only' with data=null otherwise. It also clarifies a token condition, adding useful context beyond the annotation.

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

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

Three dense, purposeful sentences with the core purpose and behavioral details front-loaded. The parenthetical about localStorage is useful, 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?

There is no output schema, so the return-shape detail is valuable and largely covers response expectations. However, the managementToken authorization rule is incompletely specified, leaving ambiguity for an agent that does not already have an account-token context.

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

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

With 0% schema description coverage, the description must compensate. It adds some meaning by explaining the account-token/managementToken relationship and the data scopes, but it never fully defines when managementToken is actually required or what ownership implies. dropId is left largely to inference from name and schema 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 states a specific action and resource: reading a drop's app data, defined as the shared-memory state / JSON snapshot mirroring localStorage. This clearly distinguishes it from sibling read tools like dropyour_read_content and dropyour_read_app_files, which target different 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?

It gives a clear use condition: use this when you need to answer questions about what the app holds, e.g., to inspect the app's stored state. It doesn't explicitly name alternatives or exclusions, but the context is strong enough for an agent to route correctly.

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

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

Beyond the readOnlyHint annotation, the description discloses that documents are untrusted visitor-controlled data, that ordering is most-recently-updated first, that pagination continues via an opaque cursor, and that writes belong to the app's own code. These are meaningful behavioral disclosures that help an agent use the tool safely.

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

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

Three sentences front-load the core operation, then pagination, then a critical security warning and read-only note. There is no filler, and the IMPORTANT warning earns its place because it changes how the agent must treat returned document content.

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

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

For an 8-parameter paged query with no output schema, the description covers the essential operational facts: graduated-app scope, cursor continuation, termination, default ordering, and untrusted document content. The remaining parameter details are already present in the input schema, so nothing essential is missing for selecting and invoking the 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?

The description adds important cursor semantics not fully captured in the schema: pass the returned cursor for the next page, and no cursor means the end. It also reinforces the default updatedAt ordering. The schema already documents sort, direction, limit, and where filters in detail, so the description appropriately supplements rather than repeats.

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 one page of a collection from a GRADUATED app's queryable store,' giving a specific verb, resource, and scope. It makes the paging behavior and default ordering explicit, which distinguishes it from sibling tools like record summaries or data writes.

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 exactly how to fetch a page, how to continue with the returned cursor, and how to detect the end. The read-only note also indicates this tool is not for writes, though it does not explicitly name sibling alternatives for summary or non-graduated data access.

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 readOnlyHint annotation by disclosing that nothing is downloaded, that levels 1-3 return graduated=false, and that degraded=true means the backend was unreachable and the result is 'unknown', never 'empty'. These behavioral edge cases are exactly what an agent needs to interpret results correctly.

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

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

Three sentences deliver the core output, the non-destructive behavior, and the two critical edge cases with no wasted words. The key outcome is front-loaded and the caveats follow in a logical, scannable order.

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

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

For a read-only tool with no output schema, the description covers the output shape, the graduated requirement, and the degraded/unknown distinction. It omits managementToken semantics and behavior for invalid or unknown dropIds, so it is not fully complete, but it is largely sufficient for a small summary endpoint.

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

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

Schema description coverage is 0%, so the description needed to explain dropId and managementToken, but it does not mention either parameter. dropId's purpose is inferable from the name and pattern, but managementToken's role is completely unexplained, leaving the agent without guidance on authentication or parameter 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?

The description states a specific verb and resource: it summarizes what a graduated app stores, with one line per collection containing record counts and byte sizes. It clearly distinguishes this from sibling tools like dropyour_records_list by focusing on aggregate store metrics rather than individual records. The 'GRADUATED app' qualifier adds essential scope.

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

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

The description clearly indicates that the tool applies only to graduated apps and that levels 1-3 have no store, giving an explicit when-not-to-use condition. It does not explicitly name an alternative sibling tool for ungraduated apps or for record-level access, but the context is clear enough for an agent to route correctly in most cases.

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

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

Annotations already signal idempotentHint and destructiveHint, and the description adds meaningful behavioral context: version_conflict refusal on stale writes, unconditional overwrite semantics, server-side authorship attribution, and the deliberately absent delete path. It does not cover auth requirements or rate limits, but the destructive and concurrency behaviors are well disclosed.

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

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

The description is longer than average but information-dense. The core action and scope are front-loaded, and every additional sentence addresses a consequential behavioral aspect: concurrency, authorship, idempotent replacement, and deletion policy. It is not padded, but the paragraph could be tightened without losing meaning.

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 6-parameter write tool with no output schema, the description covers row scope, create/replace semantics, optimistic concurrency, server attribution, and the absence of delete. It does not describe the success response shape, which remains a gap given there is no output schema, but the operational behavior is sufficiently specified 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 description adds real semantic value beyond the schema, especially for expectedUpdatedAt: it explains that the value should come from records_list and that a mismatch produces version_conflict. It also clarifies the create-vs-replace behavior tied to id and the unconditional overwrite mode. With schema coverage at 67%, the description partially compensates for the remaining undocumented parameters, though managementToken and dropId are left to 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?

The description opens with a specific verb-object pair: 'Write (or replace) ONE row in a graduated app's store' and immediately scopes the behavior with 'without republishing anything.' It also distinguishes the store table from read paths by noting it is the same table app code reads with records.list/get, and explicitly mentions that no delete verb exists, helping disambiguate from 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?

The description gives clear operational guidance: pass expectedUpdatedAt for optimistic concurrency, omit it to create or overwrite unconditionally, and be aware that writes are last-write-wins. It also frames when this store-write tool is appropriate versus read operations and explains why deletion is intentionally unavailable. However, it does not explicitly contrast this tool with sibling write tools such as dropyour_write_data.

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

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

Annotations are minimal, so the description carries the transparency burden. It fully discloses that checks are REAL requests with side effects, that they count as invocations, that the same 10-second deadline applies, that slow routes read as failures, that rollback requires tier 4, and that repeated attempts are rate-limited. This is far 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 long but every sentence carries a distinct, useful fact: transaction semantics, rollback behavior, output contents, tier constraints, onFailure behavior, side-effect warnings, deadline, and rate limiting. It is front-loaded with the one-sentence summary and then expands into necessary operational detail without repetition.

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

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

For a complex publish-verify-rollback tool with no output schema, the description covers safety, failure outcomes, logging details, tier gating, side effects, timeouts, and anti-abuse limits. An agent has enough context to decide whether to call it and what to expect on both success and failure paths.

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

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

Schema description coverage is only 17%, so the description must compensate. It adds strong meaning for verify with examples ('my page answers', 'my JSON route answers 200', 'the missing route really answers 404') and clarifies the expectStatus default of 200 even though the schema does not. However, html, zipBase64, and managementToken remain unexplained, leaving a partial gap.

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

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

The description opens with a concrete verb and resource: 'Publish new content AND check it works, in one transaction.' It clearly distinguishes this from siblings like dropyour_publish, dropyour_replace, and dropyour_rollback by emphasizing the verify-and-rollback transaction, and even notes that a release with nothing to verify is just dropyour_replace.

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 the rollback default as 'the safe way to ship,' and use onFailure='keep' when you want to inspect the broken state or when no version history exists. It also explains when the tool refuses upfront (tier 1-3) and warns against repeated publish/fail/republish loops, so an agent knows both the right conditions and the wrong conditions.

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?

Despite annotations already declaring idempotentHint=true and destructiveHint=false, the description adds valuable context: the URL never changes, visitor browser data survives the update, and a drop keeps its type. It also clarifies authentication behavior with account tokens, which is not visible in the annotations and materially changes how the tool may be invoked.

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

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

Four sentences, each carrying distinct information: the core action, the URL-stability guarantee, the type-lock constraint, and the authentication simplification. The description is front-loaded with the main purpose and contains no redundant elaboration of schema details.

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

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

For a 4-parameter tool with no output schema, the description covers the key invocation pitfalls: the zip restriction, the type invariant, the stable URL behavior, and token requirements. Combined with the input schema's dropId pattern and parameter descriptions, an agent has enough context to call this tool correctly without needing to guess at undocumented behavior.

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

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

Schema description coverage is 75%, and the description goes beyond the schema by explaining the relationship between html and zipBase64 (tier-4 graduation), the type-matching constraint, and when managementToken can be omitted. dropId is not discussed, but its pattern in the schema is sufficient and it is the sole required parameter.

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

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

The description opens with a specific verb and resource: 'Replace the content of an existing drop.' It also clearly distinguishes the operation from related tools by stressing 'existing' content replacement, the type-lock rule, and the URL-stability contract, so an agent can tell it apart from publish, delete, or rollback.

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 concrete conditions for when replacement is valid: HTML for single-file drops, base64 .zip only after tier-4 graduation, same-type replacement, and token requirements for owned drops. It does not explicitly name sibling alternatives like dropyour_publish or dropyour_delete for disambiguation, but the constraints make the appropriate usage clear 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 already mark the tool as idempotent and non-destructive, and the description adds meaningful behavioral context: it only moves a pointer, no bytes travel, nothing is rebuilt, the URL never changes, unknown versions are refused, and version 0 has special restoration semantics. No contradiction with annotations.

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

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

The description is dense and purposeful, with the core operation front-loaded and each sentence adding distinct value: scope, failure-path context, pointer-only behavior, prerequisite lookup, version-0 meaning, and a clear exclusion for regular-drop demotion.

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

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

The description is strong enough for an agent to select and invoke the tool correctly: it covers purpose, prerequisites, failure behavior, and non-destructive semantics. Minor omissions are the optional managementToken semantics and what a successful response looks like, which would matter slightly more since no output schema is provided.

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

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

Only the version parameter has schema-level description coverage, but the description compensates substantially by explaining that the version must come from dropyour_list_versions, that unknown values are rejected, and what version 0 means. It does not elaborate on dropId or managementToken, leaving a minor gap, but the critical parameter semantics are clarified.

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

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

The description states a specific action and resource: rolling a GRADUATED app back to a previously published version. It also clearly distinguishes itself from dropyour_release and from stepping an app down to a regular drop, so an agent can tell it apart from siblings without opening schemas.

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

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

The description gives explicit when-to-use guidance: rely on it for the expected failure path, or reach for it directly when you published something broken outside that loop. It also states preconditions — call dropyour_list_versions first and pass a known version — and warns against using it for demoting an app to a regular drop.

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, so the description carries the burden—and succeeds. It warns that setting replaces the code-armed schedule, that test is a real invocation which can actually write, and that read is where silent no-write runs become visible. No contradiction with the annotations is present.

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 long but information-dense; every sentence carries behavioral weight. The ALL CAPS emphasis highlights non-obvious behavior, though a few clauses could be tightened without losing value.

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 reasonably covers return semantics for read and test, behavior for set and cancel, and important side effects. The remaining gaps are the undocumented required dropId, managementToken's role, and what set/cancel return on success.

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

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

Schema description coverage is only 25%, and the description does add real meaning to the action enum and the at time window. However, it never explains dropId or managementToken, leaving two of four parameters semantically undocumented despite the low 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 names a concrete resource ('your app's clock') and a precise set of verbs: read, set, cancel, and test. Each action is explained, and the tool is positioned distinctly from the logging sibling by directing the agent to dropyour_logs as the companion for inspecting app output.

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 action comes with an explicit when-to-use trigger: read for status including silent no-write runs, set for scheduling, cancel for dropping, and test immediately after writing a scheduled handler. It also names dropyour_logs as the alternative for reading app output and restricts use to Tier 4.

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. The description adds valuable behavioral context beyond those annotations by explicitly stating that deleting a non-existent name is not an error and that the final state is what was requested, which clarifies the idempotent semantics in practical terms.

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 short sentences deliver the core action and the most important behavioral nuance without any filler. The primary purpose is front-loaded, and the idempotency clarification 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?

The tool is simple and the annotations cover safety and idempotency, but the description omits meaningful guidance for two of three parameters, especially `managementToken`. With no output schema and zero schema description coverage, the definition is adequate but leaves notable gaps in parameter understanding.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies the `name` parameter. It does not explain `dropId` or the optional `managementToken`, and the schema only provides patterns, not semantic meaning. This leaves significant parameter ambiguity for an agent.

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

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

The description uses a specific verb and resource: 'Delete a secret from a graduated app's vault by name.' It clearly identifies the action, the target, and the selection mechanism (name), distinguishing it from related tools like dropyour_secret_set and dropyour_secrets_list.

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 to use this tool: deleting a secret by name from a graduated app's vault. It does not explicitly state alternatives or when not to use it, but the deletion purpose is unambiguous, and the sibling tools list makes the alternatives inferable.

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 idempotent and destructive hints, the description discloses critical behavior: encrypted at rest, never readable back by anyone, the egress membrane attaching it to outbound requests, no TLS termination, no injected certificate authority, rotation on existing names, and write-only semantics. This is exactly the kind of context an agent needs. No contradiction with annotations.

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

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

The description is long but every sentence carries necessary operational detail: security model, attachment mechanics, form semantics, rotation, constraints, and permissions. The most important fact—'NEVER readable back'—is front-loaded, and nothing reads as 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 description is complete enough for correct invocation: it covers when to use it, what happens at runtime, how the form parameter behaves, all relevant constraints, auth requirements, and destructive rotation behavior. No output schema exists, but for a secret setter the return value is not necessary for correct use.

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 only 33% schema coverage, the description compensates strongly: it explains the form variants (bearer, header, basic, query), name format, host wildcard rule, value size limit, and managementToken ownership. The only notable gap is that dropId is never explicitly described; its meaning must be inferred from the sibling naming convention and the phrase 'for an app.'

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

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

The description uses a specific verb and resource: 'Store a SECRET for a graduated app (tier 4), bound to a host pattern.' It leaves no doubt about what the tool does and is clearly differentiated from the sibling secret_delete and secrets_list tools by describing the write-once, egress-bound behavior.

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

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

The description clearly identifies the intended context: graduated/tier-4 apps, secrets bound to a host pattern, and ownership requirements via account token or managementToken. It does not explicitly enumerate when not to use it or compare against alternatives, but there is no competing setter among the siblings, so the usage context is sufficiently 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?

With readOnlyHint=true, the annotation already signals a safe read operation. The description adds a meaningful behavioral guarantee that secret values are never returned and only metadata fields appear, which is important context beyond the structured annotations. Pagination and ordering are not disclosed, but the core behavioral trait is well covered.

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 the core scope is front-loaded. The parenthetical metaphor adds rationale but is slightly decorative; overall, the text is still efficient and well structured.

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

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

The description covers purpose, output scope, and a use case, and the annotation covers read-only safety. However, with no output schema and 0% parameter coverage, it omits parameter semantics, ordering/pagination behavior, and a clear definition of what makes an app 'graduated.'

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

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

Schema description coverage is 0%, and the description does not explain dropId or managementToken at all. It only implies a 'graduated app' context, leaving both parameter meanings to be inferred from the schema's names and patterns.

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

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

The description uses a specific verb and resource ('List a graduated app's secrets') and clearly bounds the output to names, host bindings, and dates only. This distinguishes it from secret mutation tools, though it does not explicitly contrast it with sibling list 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 an explicit intended use: 'Use it to know what to rotate or delete.' It provides clear context for when the tool is helpful, but it does not mention alternatives or exclusions, so an agent must infer when not to use it.

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

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

Annotations already mark readOnlyHint=true, and the description adds non-obvious behavior: it reads the DROP's record rather than the running app, managementToken is not needed for owned drops with an account token, and view count is approximate. No contradictions.

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 compact sentences with useful information front-loaded: fields first, auth nuance second, disambiguation last. No filler or repeated schema info.

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

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

For a 2-param read-only tool with no output schema, the description lists expected return fields, handles auth guidance, and directs the agent to the correct sibling for live app state. Nothing needed to call it correctly is missing.

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

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

Schema has zero description coverage, but the description partially compensates by explaining managementToken's role and when it can be omitted. However, it does not explain dropId beyond the tool name and requires the agent to infer it is the drop identifier; the coverage gap is not fully closed.

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 ('Get a drop's status') and enumerates the returned fields, which is enough to identify it. Explicitly distinguishes itself from dropyour_schedule by contrasting the drop record vs the running app, so an agent can disambiguate.

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

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

Provides explicit selection guidance: the first sentence covers record-level info, and the second sentence determines when a token is needed; the final sentence names the sibling and condition ('for a graduated app's live state... call dropyour_schedule'). It is clear when to use this tool versus alternatives.

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 provide idempotentHint, so the description carries the behavioral burden. It explains visibility semantics (private = link-only + noindex, public = indexable), warns that switching to public triggers a stricter content re-scan and may be rejected, and clarifies auth requirements for badgeHidden and managementToken. These details add real value beyond the annotation and 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?

Three dense, front-loaded sentences: the first enumerates what can be changed, the second warns about the public-switch side effect, and the third clarifies auth. Every sentence earns its place with no filler or repetition.

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

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

For an 8-param mutation tool with only idempotentHint and no output schema, the description covers the critical behavioral, auth, and edge-case context an agent needs to call it correctly. The few omitted details, such as publishAt and tags, are already documented in the schema, so the overall definition is complete enough.

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 63%, and the description adds meaning where the schema is silent or minimal: visibility enum semantics, managementToken vs account-token ownership, and the badge's Pro requirement. It does not mention publishAt or tags, but those already have schema descriptions, so the combined coverage is strong.

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 concrete verb+resource: 'Change a drop's visibility... its expiration, or remove the badge... or its private name,' so an agent immediately knows what the tool does. It does not explicitly contrast with siblings like dropyou_publish or dropyou_schedule, but the settings-update scope is clear.

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

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

The description implies when to use the tool: when you need to change visibility, expiration, badgeHidden, or the private name. However, it does not explicitly state when to prefer a sibling tool or when this tool should not be used, such as for publishing/scheduling operations.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: an invalid token silently degrades to anonymous rather than producing an error. This is exactly the kind of non-obvious behavioral trait an agent needs to interpret results correctly.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the authentication caveat is placed where it adds the most value.

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, read-only identity check, the description fully covers what the tool does, when to use it, and the key failure behavior. No output schema exists, but the description sufficiently indicates what the response covers: resolved tier and limits.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The description appropriately focuses on what the call reports rather than inputs.

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: 'Check how this session is authenticated: resolved tier (anonymous / free / pro) and its limits.' It clearly identifies the tool as an identity/tier inspection utility and is distinguishable from siblings like dropyour_status or dropyour_logs.

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

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

The description explicitly tells the agent when to call it: 'Call this after configuring an account token (dyk_...) to confirm it is recognized.' It also gives a critical usage nuance: an invalid token silently degrades to anonymous, which tells the agent what to verify.

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 destructiveHint annotation by explaining exactly what gets replaced, when writes are rejected (version_conflict), and why re-reading and retrying is required. It also discloses the server-memory limitation and clarifies the managementToken condition for account drops.

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

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

The description is dense but each sentence earns its place: operation, workflow, constraint, failure mode, and authentication are all covered. The key action and scope are front-loaded, and the version-conflict guidance is clear without padding.

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

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

The description covers prerequisites, exclusions, failure behavior, and auth context for this state-replacement operation. The only notable gap is the success return value, since there is no output schema; however, this is a minor omission for a tool whose core behavior is so clearly specified.

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

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

Schema coverage is only 50%, so the description must compensate. It does for data and expectedVersion, adding that data must be the FULL object and expectedVersion must come from read_data. managementToken is partially clarified by saying owned drops need none, but dropId itself is left to inference.

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: it writes/replaces a drop's shared-memory app data. It clearly distinguishes itself from read_data and explains the data it operates on, so an agent can tell it apart from sibling tools without opening their schemas.

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 explicitly instructs to read first with read_data, modify, and write back the whole object. It also gives a firm exclusion: anonymous drops cannot be written here because their data lives in the browser. The expectedVersion requirement adds a clear precondition for successful use.

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