Dropyour

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

Annotations only cover idempotency and non-destructiveness; the description adds substantial behaviour beyond them — 404 when nothing is declared, that the tool grants nothing beyond the route and app guards apply unchanged, that declarations are explicit rather than derived from pushed code, the beta SDK/2026-07-28 revision caveat, and a data-vs-instructions prompt-injection warning. This is well above the bar set by 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?

Front-loads the core capability and URL before the action breakdown, and every clause carries operational weight (byte limits, prefix rule, 16-tool cap, 404 condition). It is dense — parenthetical asides and the SDK-revision note lengthen it — but nothing is 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 7-parameter mutation-style tool with no output schema, this covers preconditions, limits, action semantics, and the safety caveat on returned data. Remaining gaps are the undocumented managementToken (auth requirement) and the shape of what 'lister' returns, though the data-not-instructions warning partly addresses the latter.

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 29%, so the description must compensate, and it largely does: it constrains name (lowercase, no 'dropyour_' prefix and why), description (≤500 bytes), inputSchema (JSON Schema, ≤4KB), and route (the app path the call POSTs to). Gaps remain — dropId's 8-char pattern and managementToken are never explained in prose.

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

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

States a specific verb+resource: makes the caller's app callable as an MCP server at a concrete URL, and enumerates the three actions (declarer/retirer/lister) with what each does. An agent can distinguish this from siblings like dropyour_publish or dropyour_graduate 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?

Explicitly routes across the three action values: declare ONE tool, revoke that surface, or inspect what is declared. It also states the precondition that makes the surface exist at all ('live as soon as ONE tool is declared; no tool declared = no /mcp at all (404)') and the 16-tool ceiling.

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

Annotations already declare openWorldHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds substantial context beyond that: the hard 10-second deadline with a 503 fallback, that guard traversal (password page, scheduled 404) is expected behavior, and that no url parameter exists by design. The one tension is that it stresses 'if the route you call writes, it really writes' while destructiveHint=false — defensible, since the write is performed by the called app rather than by this tool, but it is not fully reconciled.

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 return values, and nearly every sentence carries operational weight (deadline, guards, injection warning). It is longer than the norm and has a little redundancy in the guard explanation ('That is information about your drop, not a limitation'), which keeps it off a 5.

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

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

With no output schema, the description correctly takes on return values (status, headers, duration, body, requestId for log correlation) and failure mode (503 on timeout). It is nearly complete for a 6-parameter tool, missing only auth expectations and the body parameter's semantics.

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

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

Schema coverage is only 33%, so the description has to carry more than it does. It explains the deliberate absence of a url parameter and the dropId-plus-relative-path model, both useful, but says nothing about the dropId pattern, method, body, or managementToken (the auth parameter an agent most needs to get right). Baseline 3 at low coverage with partial compensation.

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 — calling a route of your own drop — and immediately enumerates what comes back (status, headers, duration, body). It explicitly distinguishes itself from siblings by naming dropyour_logs as a companion and dropyour_schedule as the alternative for long work, so an agent can place it without opening another 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 a concrete trigger ('check that what you just published actually works') plus when-not guidance ('Design long work as a scheduled job ... not as a slow request') and names the sibling to use instead. It also routes the agent to dropyour_logs with the returned requestId for follow-up, which is explicit alternative 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: revoke is immediate on every channel, delegates act with their own token/session, every act is recorded under their account in the audit trail, a transfer resets access, and the tool cannot be used with a managementToken. These are exactly the operational traits annotations cannot convey, and nothing here conflicts with idempotentHint/destructiveHint.

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 action semantics before the role coverage, so the important routing information comes first. The two long enumeration lists (what 'mainteneur' covers and does not cover) are dense, but each item carries real scoping information rather than filler.

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

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

For a 4-parameter mutation tool with annotations but no output schema, the definition covers auth requirements, side effects, and role scope thoroughly. Minor gaps remain: no indication of what a 'list' response contains and no explanation of dropId's role.

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% (action and dropId lack schema descriptions), and the description compensates well: it defines each action value, the default, that email must belong to an EXISTING Dropyour account, and that revoke takes email. Only dropId's semantics remain unelaborated beyond the schema's 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 precise verb+resource ('Let ANOTHER Dropyour account maintain one of your apps... take it back at any time') and enumerates the four actions. It is clearly separable from siblings like dropyour_delete or dropyour_update_settings, since it explicitly says those powers are NOT covered by the granted role.

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

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

Strong context: it names the typical scenario (integrator transfers an app to a client, then the client grants 'mainteneur'), gives the pre-condition ('Requires a connected account (no managementToken)'), and lists what the role cannot do, which implicitly routes to other tools. It stops short of naming specific sibling tools as alternatives for the excluded 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?

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?

The description contradicts the annotation destructiveHint=false: it states that 'retire' also removes subscriptions and 'unsubscribe' removes them, which are destructive operations. Per the scoring rules, this warrants a score of 1 and an annotation contradiction flag, despite the otherwise rich behavioral detail about delivery, retries, and dead letters.

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 well-structured with uppercase section markers (DELIVERY, DEAD LETTERS, IMPORTANT) and front-loads the core concept. Given the tool's complexity, the length is justified, though some sentences 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 thoroughly covers the tool's behavior: emission syntax, delivery guarantees, retry logic, dead-letter handling, limits, and even a data-vs-instructions warning. With no output schema, it still provides enough context for an agent to understand all aspects of the tool's 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 description coverage is 56%, but the description compensates by explaining the meaning and constraints of key parameters: keys (max 8, example), label (human name, kept when omitted), route (subscriber's receiving path), subscriber dropId, and eventId for replay. Only managementToken and dropId are left to the schema, but overall the description adds significant 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 immediately states 'Events between YOUR server apps, SIGNAL ONLY' and then details each action (declare, retire, subscribe, etc.), making it clear this tool manages event topics and subscriptions. It distinguishes itself from generic call or link tools by focusing on signal declarations and delivery semantics.

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

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

The description gives explicit guidance for each action: when to use 'declare' (with keys and label), 'retire', 'subscribe' (with route and dropId), and so on. It also explains emission patterns and constraints, though it does not explicitly compare this tool to sibling tools like dropyour_call or dropyour_link, leaving some alternative-selection to inference.

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

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

Discloses behavior well beyond the annotations: it acts by creating the app, migrating data, and switching the URL, the owner is emailed, the URL is stable and visitor data preserved, and refusals change nothing while returning a complete list of reasons. Annotations cover idempotency/non-destructiveness, and the description complements them with concretely what happens and what is preserved.

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 its effect, and every sentence carries information (acting behavior, prerequisites, check mode, refusal semantics). Some clauses, such as the pricing and founding-cohort details, are verbose relative to what an agent needs to invoke it correctly.

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, side-effecting operation with no output schema and only two parameters, the description covers what the tool does, prerequisites, the dry-run option, and post-refusal behavior. Nothing an agent needs in order to call it safely appears to be missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains `check=true` precisely (get the verdict with no side effects) and characterizes `dropId` as one of the caller's drops; the schema's pattern handles the format. This substantially compensates for the coverage gap, though dropId's identity/format is left to the schema.

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

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

States a specific verb (GRADUATE) with an explicit resource and target (a drop to tier 4), and spells out concretely what results: a real backend behind the SAME URL with data carried over. An agent can distinguish this synthesis operation from siblings like dropyour_publish or dropyour_release without opening a schema.

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

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

Gives clear context for when to use it (graduating a drop to a real backend) and prerequisite conditions (account token, ACTIVE app subscription, application from the Grow space). It does not explicitly name alternative tools or the conditions that would route an agent to a sibling instead, so it falls 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?

Annotations only declare destructiveHint=false, so the description carries the behavioral load and does so richly: account/token requirements, the tier-4 graduation condition, and explicit partial-failure semantics ('If a step is refused midway, the response says exactly what was created and what to do next; nothing is hidden'). This is precisely the beyond-annotations context that helps an agent decide whether to call 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?

Front-loaded with the core action and the archive/publish model, then progressively discloses tier, account, and failure behavior. Dense but each sentence carries a distinct fact; the parenthetical asides ('you have them — from GitHub, disk, another host') are slightly padding but harmless.

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

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

With no output schema, the description compensates by describing response behavior (it reports what was created and how to apply), which is enough for an agent to act. It leaves the exact response shape and the tier-4 graduation outcome details implicit, keeping it short of fully complete for a tool with a multi-stage execution path.

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 goes beyond the schema by documenting the entry-resolution fallback ('index.html at the archive root, or the single/shallowest .html'), a rule not stated in the zipBase64 schema text and relevant to how the archive is interpreted. It does not add format or size guidance for name/expiresInSeconds, so it stops short of 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 ('Bring an EXISTING app to Dropyour in one call: zip its files and pass the archive') and immediately distinguishes itself from the two nearest siblings, dropyour_publish (single-HTML) and dropyour_graduate (multi-file, tier 4). An agent can route to this tool versus those without opening any schema.

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

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

Explains exactly when each path applies: single-HTML archive behaves like dropyour_publish with no account, while a multi-file archive requires an active app subscription and an account token, mirroring dropyour_graduate. It even states the fallback ('Without one, the entry HTML is live and the response says how to apply'), so the agent knows the outcome of both the authorized and unauthorized 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 only tell the agent this is idempotent and non-destructive; the description carries far more: a hard cap of eight links, that revocation also removes the contract, that the called app sees signed caller identity (app.caller) that cannot be forged while other requests see null, and that contract failures roll back published versions via dropyour_release/replace/patch. These are consequences an agent cannot infer from the schema or 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 purpose, constraints, and contract mechanics are front-loaded and each paragraph carries load. It is longer than strictly necessary, though — rhetorical asides ('that refusal is the platform's isolation, not an oversight', 'taking a right back cannot be harder than granting it') consume space that a denser phrasing could save without losing 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 five-parameter nested-schema tool with no output schema, the description covers everything an agent needs to call it correctly: account scoping, the eight-link ceiling, per-action requirements, contract semantics, revision behavior, and error behavior ('the answer names the consumer and the route'). Nothing material is left to inference.

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 80%, so the baseline is 3, but the description adds genuine meaning on top: `contrat` accepts at most 8 READ routes, write methods are refused, expected status defaults to 200, response schemas are minimal with extra fields allowed, and re-passing a contract bumps its revision rather than duplicating. It also clarifies that dropId is the caller except for consommateurs, where it is the callee.

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 title and opening sentence state a specific verb and resource: let one graduated app call another over the network, opened by dropId. It immediately distinguishes itself from the platform default ('no app can reach another') and from other capabilities by stating that it grants no token and no shared storage, so an agent can tell exactly what this tool is 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 enumerates the four actions with their conditions (lier opens and optionally attaches a contract, delier revokes, retirer_contrat drops the contract but keeps the link, consommateurs lists dependents), states the same-account constraint ('a link never crosses two accounts'), and gives an explicit exclusion — no token, no shared storage, the called app's guards still apply. This is when-to-use and when-not-to-use guidance in one place.

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

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

Annotations only declare readOnlyHint=true; the description adds substantive behavior the annotations do not: only LIVE drops are returned, listing works without a managementToken, delegated entries carry a role, anonymous sessions see only session-published drops, and management tokens are never persisted server-side. That is meaningful context beyond the safety hint.

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 paragraph that puts the scope distinction first and the delegated detail second. Mostly dense and useful, though the trailing sentence about management tokens not being stored server-side is peripheral for a list operation.

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 input parameters and no output schema, the description carries the burden of describing the return shape, and it does so: LIVE drops, cross-session/channel, a `delegated` section with roles. Missing only pagination/volume expectations for accounts with many drops.

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

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

There are zero parameters, so the baseline is 4. The description instead reallocates its detail to explaining how the caller's credential (account token vs anonymous) changes the result set, which is the only 'input' that matters here.

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+resource ("List your drops") and then enumerates the exact scope of what is listed: LIVE drops across sessions and channels, plus delegated apps. It never names or contrasts with the closest siblings (dropyour_records_list, dropyour_secrets_list, dropyour_list_versions), so an agent cannot rule those out from the text 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?

It clearly delineates the three invocation contexts (account token, anonymous, delegated) and tells the agent what each returns, and it points to dropyour_delegate for role semantics. It stops short of stating exclusions, e.g. when to prefer dropyour_records_list or how anonymous callers should obtain a 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?

With readOnlyHint=true already covering safety, the description adds substantial behavioral context the annotations cannot: degraded=true semantics explicitly distinguished from 'nothing published', the empty-list behavior for levels 1-3, and the fact that an account token removes the managementToken requirement 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?

The purpose and scope lead the description, and the caveats (levels 1-3, degraded) follow in a logical order. It is dense and long, but with no output schema most sentences about the inventaire payload earn their place; the EU AI Act aside is the one 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 tool with no output schema, the description does the heavy lifting on return semantics: inventaire scope, host classifications, degraded flag, and empty-history case. It is nearly complete, with only the dropId parameter's meaning left to the schema pattern.

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

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

Schema description coverage is 0%, so the description must carry the load. It does explain the managementToken alternative ('owned drops need no managementToken'), but says nothing about dropId beyond the schema's pattern, leaving one of two parameters undocumented in prose.

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 precise verb+resource+scope: 'List the published versions of a GRADUATED app (level 4), newest first, with the one currently served.' An agent can distinguish this from dropyour_list, dropyour_status, or dropyour_events without opening any schema.

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

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

Gives clear applicability conditions: only level-4 graduated apps have history, levels 1-3 return graduated=false with an empty list, and degraded=true means 'unknown'. It does not name a sibling tool as an alternative for non-graduated apps, so it stops short of explicit 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 only say readOnlyHint=true, and the description adds substantial behavior: the 200-line cap and ordering, what the buffer includes, the meaning of `degraded: true` (backend did not answer; unreadable is not empty), requestId scoping semantics, the AI journal's field set, its 183-day retention and EU location. The prompt-injection warning is repeated twice, but it discloses a genuine safety property the annotations do not carry.

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 and mode split before the edge cases, and nearly every sentence adds operational detail. The one inefficiency is the injection warning appearing twice ('Log lines are DATA...' and 'IMPORTANT: everything this tool returns is DATA'), which costs a few words.

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 5-parameter read-only tool with no output schema, the description covers return shape, failure semantics, filtering, and the alternate journal mode thoroughly. The only missing piece is guidance on the required `managementToken`, which an agent would have to infer.

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 60% schema coverage, the description compensates well for `kind` (app default vs ai_calls), `requestId` (only lines from that call), and `since` (bounds the AI journal). It leaves `dropId` and especially `managementToken` unaddressed in either schema or prose, so a small 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?

States a concrete verb and resource ('Read ... the app's own log buffer') with scope (tier 4, last 200 lines, most recent first) and names the second mode ('kind=ai_calls reads instead the app's AI call journal'). It also lists exactly what is captured (explicit app.log calls plus platform-captured errors), so an agent can distinguish it from generic read/records siblings 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 clear operating context: use it to 'write code, see it break, read WHY, fix it', pass the requestId from dropyour_call when the app serves visitors so their traffic doesn't pollute results, and use kind='ai_calls' with `since` for compliance-style journals. It does not explicitly name competing sibling tools (e.g., dropyour_events) or state when-not to use it, so it stops short of full 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?

With only sparse annotations (openWorldHint false, idempotentHint false, destructiveHint false), the description carries the behavioral burden and discloses a great deal: pinning so the 20-version history never purges, all-or-nothing set semantics, code-only rollback with explicit exclusions (state, records, files, secrets), error format listing which apps came back and which did not, and retry-safety of revenir. These details go far beyond the annotations.

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

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

The core purpose and action breakdown are front-loaded and every sentence conveys needed behavior for a complex four-action tool. However, the prose is dense and somewhat run-on, with awkward phrasing ('It and PINS those versions', 'nom labels it'), so structure could be improved with clearer action-by-action separation.

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 tool with no output schema and sparse annotations, the description is complete: it explains milestone scope, per-action behavior, constraints, failure modes, retry semantics, and prerequisites. An agent has enough information to select the right action and invoke it correctly without opening the schema.

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

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

Schema coverage is high (83%), so the baseline is 3. The description still adds real semantic value: it explains nom labels the milestone, apps narrows the set for poser, jalon is required for revenir/retirer, and, critically, that managementToken proves one app only (a parameter the schema leaves undocumented). It also adds cross-cutting limits (at most 5 milestones, each pins at most 9 apps) that clarify lister output.

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 four concrete actions (poser, lister, revenir, retirer) and the resource (milestones over a system of linked/graduated apps anchored at dropId). It clearly distinguishes this tool's scope from siblings like dropyour_rollback by stating the milestone covers every app in the system and rolls back code pointers only, not app state.

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 per-action usage guidance: poser sets, lister lists, revenir rolls back, retirer removes; it also states prerequisites (connected account for multi-app milestones) and exclusions (simple pages have no version history). It does not explicitly name sibling alternatives such as dropyour_rollback, so it stops short of a full when-to-use-vs-alternative map.

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 only idempotentHint=false and destructiveHint=false as annotations, the description carries the burden and delivers: refusal on count mismatch (nothing replaced, real count returned), refusal on version drift, contract-break refusal with automatic rollback, each patch creating a full rollback-able version, and scanning of the resulting document. This is unusually rich behavioral disclosure.

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 action is front-loaded in the first clause and every subsequent sentence adds a distinct behavioral rule, so the length is mostly justified. It is dense and dash-heavy with some filler ('the Edit semantics you already know'), which costs it the top mark.

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 7-parameter mutation tool with no output schema, the description covers failure modes, versioning, rollback, and scanning well enough to call it safely. It omits the response shape and any authentication/permission note for managementToken, which is what keeps it from a 5.

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, and it does for the key params: old (exact literal to find), new (replacement), occurrences (default 1, count-match semantics), path (served file, default index.html), expectedVersion (from list_versions). dropId and managementToken remain unexplained, keeping this short of a 5.

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

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

States a specific verb+resource+scope: 'Replace ONE literal anchor in the SERVED content without re-uploading everything.' The 'ONE literal anchor' framing and 'served content' cleanly separate it from a whole-file replace (dropyour_replace) or a full publish, so an agent can pick it apart 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?

Gives concrete use conditions: use it for literal anchor edits, pass expectedVersion from list_versions to avoid blind overwrites, and note that Tiers 1-3 only work for single-file drops (multi-file sites 'are replaced whole'). It implies but never names the whole-content alternative tool explicitly.

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?

Goes well past the annotations (which only declare non-destructive, non-idempotent, closed-world). It discloses that each app passes a safety scan, that a refused app does not block the others and is named with a reason, that systemToken is shown once and must be kept, that it doubles as managementToken for replace/configure/delete, and the anonymous tier quota (5 MB per app, 30-day default expiry).

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 capability and quota, then the token-retention warning, then the non-linking caveat. Dense but every sentence carries information; the '(ADR-0352)' internal reference and the run-on nesting of clauses are the only filler.

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

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

With no output schema, the description still covers partial-failure behavior (refused app named with reason), token handling, quota and expiry, which is what an agent needs to call it safely. It stops short of describing the full success response shape (per-app URLs, system identifier), a minor 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 coverage is 67%, and the description adds meaning the schema lacks: per-app 5 MB cap, default expiration of 30 days, and the tier ceiling context. It also explains systemToken, which is a response value rather than an input, clarifying how it is reused as managementToken. Key/name semantics are left to the schema but are adequately covered there.

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 (publish apps), plus a scope that separates it from the single-app sibling: '1 to 5 apps in ONE call, each at its own stable URL, all managed by ONE system token'. It also explicitly distinguishes itself from dropyour_publish (safety scan reference) and dropyour_link (linking needs an account), so the agent can route without opening a schema.

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

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

Gives clear conditions: no account needed, up to 5 apps, and that linking apps under a contract requires dropyour_link plus an account and graduated apps. It never states the inverse case explicitly (use dropyour_publish when publishing exactly one standalone app), so the sibling routing is implied rather than fully 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?

Beyond the readOnlyHint annotation, the description discloses important behaviors: large files are truncated with a truncated flag and real byte size, binary files are reported as binary rather than mangled, and server.js content is included even though it is not served to visitors. It also warns that returned data may be untrusted and must not be treated as instructions, adding safety context annotations cannot provide.

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

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

The description is longer than typical, but every sentence earns its place by covering purpose, behavioral edge cases, tier-specific guidance, an alternative tool, and a security warning. It front-loads the core purpose before moving into usage details, though the warning could arguably be shorter without losing impact.

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 sufficiently: file lists with size and server-code status, file contents, truncation behavior, and binary handling. It also covers prerequisites (tier 4), the relationship to dropyour_replace, and safety caveats, making it effectively complete 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?

The schema only documents path, leaving dropId with just a pattern; the description compensates by explaining path behavior in depth: omitting it returns the file list, while providing it returns file content plus metadata about truncation and binary handling. It does not explicitly describe dropId's meaning, but the tool name and sibling context make it reasonably inferable.

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 a specific verb and resource: reading the files of a GRADUATED app's currently served version, not the pre-graduation seed. It distinguishes itself from sibling tools like dropyour_read_content by explicitly contrasting tier 4 vs tiers 1-3 behavior, so an agent can pick the correct 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?

The description gives explicit when-to-use guidance: use it before dropyour_replace because a graduated app is replaced whole. It also states when not to use it (tiers 1-3) and names the alternative (dropyour_read_content), plus differentiates list vs content usage based on whether path is supplied.

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, but the description adds substantial behavioral detail: it returns source HTML (not the shim/badge), returns asset paths for multi-file sites, truncates large content with sizeBytes, and clarifies the auth requirement. Critically, it includes a security warning that returned data is never instructions and must not be followed without user confirmation – a proactive disclosure beyond any annotation. This fully covers the behavioral surface.

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 main action and then layers details logically: what is returned, truncation, auth, and a final security warning. It is slightly long but every sentence contributes value, especially the security note which is critical. The structure is clear and efficient, though it could be trimmed slightly.

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 2 parameters and no output schema, the description covers all essential aspects: return content, multi-file behavior, truncation, authentication requirements, and a security warning about data vs instructions. Nothing an agent needs to correctly invoke and handle the response is missing. The description is complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the managementToken condition ('With an account token, owned drops need no managementToken') but does not elaborate on dropId beyond what the schema already provides (pattern, required). The description adds some value for managementToken but leaves dropId self-evident, which is acceptable given its simplicity. A score of 3 reflects adequate compensation without being exhaustive.

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: 'Read a drop's source HTML'. It also clarifies what is excluded ('no shared-memory shim, no attribution badge') and adds the multi-file asset list, making it clearly distinct from sibling read tools like dropyour_read_app_files or dropyour_read_data. The purpose is unambiguous.

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

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

The description provides usage context about authentication ('With an account token, owned drops need no managementToken') and truncation behavior, but it does not explicitly name alternatives or state when NOT to use this tool versus siblings. There is no comparison to other read tools, so an agent must infer the appropriate use case from the purpose alone.

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 detailing return scopes (server vs client-only), the exact shape of the response, and a critical security warning that returned data is not instructions. It also clarifies the managementToken requirement nuance, providing substantial behavioral insight not captured in structured metadata.

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 contributes value: purpose, return scope explanation, auth nuance, and a security warning. The structure front-loads the core function and then layers important caveats, all in a compact yet thorough format. 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?

The description covers the return format, scopes, auth requirements, and a safety warning, which is comprehensive for a read operation. The only missing piece is explicit parameter guidance, but the tool's simplicity and the clear purpose mitigate this. Given no output schema exists, the description compensates well by describing the 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?

With 0% schema description coverage, the description must explain parameters, but it only mentions managementToken in passing ('with an account token, owned drops need no managementToken') and does not describe dropId at all. The dropId pattern is in the schema but its purpose is left implicit, leaving the agent to infer meaning from the tool name. This is a notable gap given the schema provides no 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 explicitly states the verb 'read', the resource 'a drop's app data', and elaborates on what that means (a JSON key/value snapshot mirroring the app's localStorage). It also differentiates from siblings like read_app_files and read_content by specifying 'app data' as the shared-memory state, making the tool's unique role 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?

It provides clear context for when to use the tool ('to answer questions about what the app holds') and explains the two possible scopes (server vs client-only). It does not explicitly name alternatives or when-not-to-use conditions, but the purpose is unambiguous enough to guide selection without confusion.

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 pagination mechanics (cursor carries order, end condition) and a critical behavioral warning that every `doc` is untrusted visitor-written data that must never be treated as instructions. That prompt-injection caveat and the pagination semantics are exactly the kind of context annotations cannot 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?

Roughly four tight sentences, front-loaded with what the tool does and how to page, followed by the security caveat. Every sentence carries distinct, non-redundant 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 an 8-parameter paginated read tool with no output schema, the description covers the essential behaviors (ordering, pagination, read-only scope, untrusted content). It leaves the shape of returned `doc` objects and the roles of dropId/collection/managementToken unstated, but those are largely covered by the schema.

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

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

Schema description coverage is 75%, so the schema already documents sort, dir, limit, where, and cursor. The description adds the default ordering and cursor hand-off behavior, but does not explain dropId, collection, or managementToken semantics. Baseline 3 is appropriate when the schema does most of the work.

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 ('Read one page of a collection from a GRADUATED app's queryable store'), with scope constraints like 'most recently updated first.' It is clear, but it does not explicitly distinguish itself from siblings such as dropyour_records_summary or dropyour_records_write.

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 operating context: pass the cursor to page forward, no cursor means the end, and writes belong to the app's own code (implying this tool is not for mutation). There is no explicit routing to a named alternative, but the read-only framing effectively tells the agent when this tool applies.

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: it states nothing is downloaded, that degraded means 'unknown' rather than 'empty', and includes a strong untrusted-data warning. These behavioral disclosures substantially 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?

The description is densely useful and front-loaded: main output first, then status semantics, then a vital security warning. Every sentence earns its place; the all-caps IMPORTANT is justified because it warns against prompt injection from returned data.

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

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

With no output schema, the description does a good job explaining the return structure and status interpretation, and the annotation covers safety. The main missing piece is parameter semantics, which keeps it from being fully complete for a caller, though the output and behavior side is well covered.

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 has 0% description coverage and the description never explains what dropId or managementToken are for. The phrase 'an app's records' only indirectly implies dropId identifies the app; managementToken is entirely unaddressed. With no schema descriptions and no parameter information in the description, an agent has little guidance for filling in these 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 description states the verb ('Summarise'), the resource (a graduated app's queryable store), and the exact output shape (one line per collection with record count and bytes). This clearly differentiates it from sibling tools like dropyour_records_list, which would return actual records rather than a summary.

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 applies: graduated apps with a store, while Levels 1-3 have no store and return graduated=false. It also explains how to interpret degraded=true. It does not explicitly compare against alternatives such as dropyour_records_list, so it stops short of 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?

Goes far beyond the idempotentHint/destructiveHint annotations: it discloses per-actor behavior (signed-in visitors see only their own rows, unsigned visitors see an empty set, the owner always sees everything), the NULL-author edge case, the write-refusal rule for others' rows, and that state blob/realtime channels are unaffected. The 'reversible with the same call' and 'declared, never derived' statements add operational traits not inferable from the schema or annotations. No contradiction with annotations — idempotency and non-destructiveness are consistent with the described 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?

The description is long but front-loaded: the core statement and the two values come first, followed by edge cases, exclusions, and meta-properties. Every sentence carries semantic weight — the NULL-author rule, the write-refusal behavior, and the scope exclusions each prevent real surprises. It could be tightened slightly, but the density is justified by the conceptual richness of the permission model.

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

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

For a tool with no output schema and no per-parameter schema documentation, the description provides everything needed to call it correctly: the meaning of all required parameters, the behavioral consequences of each value, edge cases, scope exclusions, and reversibility. The only omissions — managementToken semantics and possible error responses — do not impede correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It thoroughly explains the critical parameter 'visibilite' with full semantics of both enum values, and gives meaningful context for 'collection' (ONE collection) and 'dropId' (your graduated app's store). However, the optional 'managementToken' parameter is never mentioned, leaving a small gap in an otherwise strong compensation for the empty schema.

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

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

States a specific verb and resource: 'Declare the visibility of ONE collection of your graduated app's store.' It names the two allowed values upfront ('partagee' vs 'par-auteur') and defines the scope as the per-visitor data path. The description clearly distinguishes this from sibling data tools like dropyour_records_list, dropyour_records_write, and dropyour_read_data by focusing on read-scoping policy rather than data 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?

Gives clear context on when to use the tool — whenever you need to change who can read a collection in a graduated app — and explains both value options thoroughly so an agent can decide between them. The 'What this does NOT cover' paragraph explicitly excludes the shared state blob and realtime broadcasts, preventing misuse. It stops short of naming a sibling alternative for those excluded behaviors, but the tool is largely self-contained as a per-collection visibility setter.

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 only declare openWorldHint/idempotentHint/destructiveHint; the description adds far more: automatic rollback semantics, tier-dependent refusal, checks being REAL requests that count as invocations and really write, the shared 10-second deadline, rate-limiting on repeated attempts, contract replay via dropyour_link with brokenContracts output, and a prompt-injection warning on returned data. This is exceptional disclosure beyond structured fields.

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 dense, front-loaded with the core publish-and-verify purpose before secondary details. Nearly every sentence carries distinct operational value, though the length is at the upper edge and could be tightened without losing substance.

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 still describes what comes back: the failing check plus app log lines, and brokenContracts naming consumer and route. Combined with side-effect, deadline, rate-limit, and tier coverage, an agent has everything needed to invoke this 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 coverage is only 17%, so the description carries much of the burden. It explains verify items well (path plus expected status defaulting to 200, with examples) and the onFailure enum's meaning, but html, zipBase64, dropId, and managementToken are never addressed. Partial compensation for a real coverage gap.

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

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

States a precise compound verb+resource: publish content and verify it in one transaction, with automatic rollback. It explicitly distinguishes itself from a sibling by noting that a release with nothing to verify is just dropyour_replace, so an agent can route correctly 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 conditions: the safe default of rollback, the onFailure='keep' case for inspecting a broken state or on drops without version history, and tier gating (refused before publishing on tier 1-3). It names alternatives and exclusions rather than leaving them to inference.

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

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

Annotations only declare idempotentHint and destructiveHint=false, but the description adds substantial behavior: the URL/origin contract keeps browser data intact across updates, drop type is preserved, contract checks under dropyour_link can refuse a breaking version and restore the previous one, plus the consumer_contract_broken error and token requirements. This is rich context well beyond the structured fields.

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

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

A single dense paragraph, front-loaded with the core action and immediately followed by the origin-contract and type-preservation constraints. Every sentence carries information, though the contract-check clause is packed and could be split for 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 and annotations covering idempotency/safety, the description covers what changes, what is preserved, failure behavior, and error signaling. It stops short of documenting permissions beyond token ownership and says little about the returned result, but it is otherwise call-ready.

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% (dropId relies on the pattern alone). The description adds meaningful semantics on top of the schema: html applies only to single-file drops, zipBase64 requires tier-4 graduation, and managementToken is unnecessary for account-owned drops. This exceeds the baseline-3 expectation for high 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?

States a specific verb (replace) and resource (an existing drop's content), and distinguishes itself from siblings like dropyour_patch, dropyour_publish, and dropyour_rollback by describing the in-place, URL-preserving semantics. An agent can tell what this does 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 clear conditional context: HTML for single-file drops, base64 .zip only once the app has GRADUATED to tier 4, and account-token ownership removing the need for managementToken. It does not, however, explicitly route the agent away from alternative tools (patch/publish/rollback), so it lacks true 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 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?

The description goes well beyond annotations by disclosing that the old token is killed, every previously shared management link dies, and the new token is returned only once. It also flags the hidden cost of rotating a merely misplaced token, which is valuable behavioral 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 about 80 words across three sentences, with the core action front-loaded. Some phrasing is elaborate, but every sentence carries operational meaning and the warning about consequences 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 description covers purpose, two usage modes, one-time output, and the main side effect, which is sufficient for a two-parameter tool with no output schema. The only missing details, like the dropId format, are already available in the input 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?

With 0% schema description coverage, the text compensates by explaining that the old token corresponds to managementToken and that recovery can happen via the connected account when the token is lost. It implies that managementToken is optional for recovery, though it does not explicitly name dropId or map each 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 names a specific operation: mint a new management token and kill the old one, and it distinguishes the two modes (rotation with the old token, recovery with a connected account). This clearly separates it from sibling tools like secret_set/secret_delete or settings updates.

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 states when to use the tool: lost or leaked token, with rotation vs recovery spelled out. It does not give explicit when-not-to-use guidance or name alternative tools, but the context is clear enough for an agent to decide.

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?

The description carries substantial behavioural load that annotations do not: the 30-day retention after a system is deleted with its apps, the refusal of all other actions on a suppressed system, the "versions saved first" / "stops at the first failure" semantics of apply, apply's resume-then-no-op idempotency, the one-time 24h transfer link that cancels its predecessor and resets every management token, and the auth requirement ("connected account (no managementToken)"). One tension worth noting: destructiveHint=false sits awkwardly beside a 'delete' action and a 'transfer_link' that resets all management tokens, though the description's precision means this is annotation coarseness rather than a description error.

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?

Almost every clause carries information an agent needs for one of 17 actions, but the whole thing is delivered as a single unbroken paragraph with no per-action segmentation, headers or line breaks. Front-loading is good (core definition first, action semantics after), yet the density forces an agent to parse the entire block to find the one action it cares about.

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 this complex with no output schema and thin annotations, the description covers what an agent needs: what each action returns where it matters (systeme.json contents for export, call permissions and compatibility verdicts for view, two files for contracts, dossier status for proof), destructive and retention consequences, ordering guarantees in apply, and the account-level prerequisites. Nothing essential to 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?

With 11 parameters at 55% schema coverage, the description does real work: it names which parameters each action consumes (name/apps for create, systemId/dropId for add/remove, email for delegate, client for label, routes plus a server-app dropId for private_routes, enabled for shared_identity, manifest for plan/apply) and adds constraints the schema lacks, such as apps being dropIds you own and app membership being limited to one system. Minor gaps remain (name length/rules, systemId sourcing) but 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?

The opening sentence gives a concrete verb and resource ("Manage SYSTEMS: named groups of up to 9 of your apps, handled as one") and the 17 enumerated actions make the scope unmistakable. It references dropyour_delegate but never distinguishes itself from the sibling dropyour_publish_system, which overlaps with its plan/apply publishing behaviour, leaving one sibling boundary unresolved.

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 is explained in enough detail that an agent can infer which action to pick for a given goal (e.g. 'delete' removes only the grouping, 'plan' previews before 'apply'). However, there is no explicit when-to-use guidance at tool level, no statement of when to prefer dropyour_publish_system, dropyour_link or dropyour_delegate over this tool, and no exclusions.

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

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

Annotations only declare idempotentHint and destructiveHint=false; the description adds substantive behavior beyond them: public switching triggers a stricter content re-scan and may be rejected, badge removal requires a Pro token, and empty strings clear fields. Auth and failure-mode context are disclosed rather than implied. It omits any note on response/confirmation behavior, which keeps it from 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?

Front-loaded with the core action, and every clause carries information (no filler). It is a single dense sentence with nested parentheses that makes scanning slightly harder, but nothing is redundant.

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

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

For an 8-parameter mutation tool with no output schema and thin annotations, the description covers the highest-risk behaviors (public re-scan rejection, token requirements, badge gating) that an agent must know before calling. Gaps remain around tag replacement and scheduling interactions, but the critical decision points 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?

Schema coverage is 63% (8 params), so the description has real work to do and does it for the ambiguous ones: visibility is unpacked into 'private = link-only + noindex, public = indexable', expiration semantics and name-clearing are explained beyond the schema. It adds no meaning for tags, publishAt, or dropId, which are left entirely to the schema.

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

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

States a specific verb+resource ('Change a drop's settings') and then enumerates exactly which settings: visibility, expiration, badge, private name. An agent immediately knows the scope. It does not differentiate itself from nearby siblings like dropyour_patch, dropyour_replace, or dropyour_publish, 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?

Gives conditional prerequisites ('badgeHidden — Pro account token required', 'With an account token, owned drops need no managementToken'), which is real routing/auth guidance. However, it never states when to prefer this tool over dropyour_patch/replace/publish for the same resource, so the when-to-use-vs-alternative question is left to inference.

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

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

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.