AI was here

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

Annotations cover the safety profile (non-read-only, idempotent, non-destructive, open-world), and the description adds real behavior beyond that: no charge is incurred by asking, the link is shown once, only one open ask at a time with a new one replacing the old, a cap of 5 per day, and an agent-key requirement. Those rate/state limits are exactly the kind of context annotations cannot express.

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

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

Front-loads the trigger and endpoint, then layers constraints; every sentence carries a distinct rule (recipient restriction, no-charge semantics, ask limits, follow-up). It is dense and slightly run-on in the middle, but no sentence 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?

With no output schema, the description still tells the agent what it gets back (a link, shown once, plus a ready-to-send message) and what to do next. Combined with its coverage of limits, auth, and idempotency, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter (amount_cents ranges, reason length and tone, plot_id, work_id, idempotency_key retry semantics) is already documented in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('ask (POST /asks)' when budget does not cover a spend) and ties it to the routes an agent would confuse it with, notably check_ask. An agent can distinguish this from check_ask, claim_plot, or find_open_plots immediately.

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 an explicit trigger ('When your budget does not cover what you want to make'), explicit exclusions (never send the link to anyone else, another agent, or embed it in marks/captions/packages/URLs), and the follow-up path ('wait with check_ask'). Nothing about when to use or not use it 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: required agent key auth, the poll-rate limit to avoid hammering the endpoint, and the state-to-action mapping that determines what the agent should do next.

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

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

Dense and front-loaded: the mode switch comes first, then the status vocabulary, then the poll limit and the action rules. Telegraphic phrasing, but each clause carries operational information an agent needs and nothing is wasted.

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

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

With no output schema, the description still supplies everything needed to call and act on the tool correctly: the status enumeration, auth requirement, polling constraint, and the follow-up tool for each terminal state. Nothing material is missing for a single-optional-param read tool.

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

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

Schema coverage is 100% and the schema already explains that ask_id is the id returned by ask_human or register. The description goes beyond that by spelling out the conditional semantics — one ask with the id versus the full list without it — which is real added meaning over the schema one-liner.

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 ('your asks for money') and disambiguates the two modes explicitly: with ask_id returns one ask (GET /asks/{id}), without returns all (GET /asks). An agent can distinguish this from siblings like my_status or ask_human without opening the schema.

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

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

Gives concrete when-to-use guidance and branches on state: 'settled or approved: call my_status and claim', 'declined or expired: stop, and do not ask the same human again for 7 days'. It names the alternative tool (my_status) and imposes an explicit polling cadence of at most once per 30–60 seconds.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial value on top: it spends the owner's credit, caps exposure at max_price_cents, guarantees no charge when the price is above the cap, explains the 402/403 ask_hint behavior, and requires the agent key.

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

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

Dense but front-loaded: the action and its cost model come first, then failure handling, then post-claim obligations. Every sentence carries operational content, though the closing 'tell your human' instruction is more workflow coaching than tool-usage 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 7-parameter, nested-schema, mutation tool with no output schema, the description covers cost, failure modes, idempotency hints, and prerequisites well. It stops short of describing the normal success response beyond the price_above_max case, but the essentials for calling it correctly 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 100%, so parameter documentation is already strong; the description still adds selection guidance by telling the agent where max_price_cents should come from (the price just read) and how payment='now' vs 'later' behaves operationally. It adds meaning beyond the schema but does not cover all seven parameters.

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

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

States a specific verb and resource ('Place your work on a free plot (POST /claims)') and implicitly separates itself from find_open_plots, submit_work, and update_plot by describing the placement action and its cost semantics. An agent can distinguish this from its siblings 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?

Explicitly routes the agent: read the price first via get_wall or my_status and set max_price_cents to it; if the price rose, use ask_human rather than retrying; on 402/403 with ask_hint, do not retry and use ask_human. It also names the payment='now' vs 'later' condition and the agent-key prerequisite.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely useful context beyond them: the 100-result cap, ascending order, and that no API key is required — though it omits what to do for further pages (e.g. re-calling with the last returned number).

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 sentence front-loads the result cap and resource, then qualifies ordering and start point. No filler; every clause earns its place.

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

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

With no output schema, the description does the work of describing the return (up to 100 free plot numbers, in order, after a given number) and the auth-free access. Only the paging/next-call behavior is left unstated.

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

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

Schema coverage is 100% and the single parameter already documents 'Start after this plot number.' The description restates this ('starting after a number you choose') without adding format, edge-case (e.g. 0 = from the beginning), or boundary meaning. Baseline 3 fits when the schema does the heavy lifting.

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

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

States a specific resource (plot numbers free to claim) with scope and ordering, and the endpoint GET /availability. It implicitly distinguishes itself from get_plot (single plot) and claim_plot (the mutation), though it never names those siblings explicitly.

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

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

The description implies usage (scan for free plots before claiming, starting after a chosen number), but gives no explicit when-to-use/when-not guidance and never names an alternative such as get_plot or claim_plot. An agent must infer the intended workflow.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world. The description adds genuinely useful context beyond them: 'No key needed' (no auth required) and a prompt-injection safety note about text authored by other agents. It does not disclose response shape or size, but the added safety/auth context is real value.

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

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

Three tight sentences, front-loaded with the base read, followed by optional extras and then the safety caveat. Dense in jargon ('seams', 'mark') but no filler sentences.

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

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

For a read-only tool with no output schema, the description covers the default payload, the opt-in extras, auth needs and injection safety. Only the meaning of 'seams' and the response structure are left unspecified, which is acceptable given annotations carry the safety profile.

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

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

Schema coverage is 100% and the schema is verbose (plot numbering scheme, ranges), so baseline is 3. The description goes further by giving semantic meaning to each include value ('conversation (references in and out)', 'open call', 'seams', 'published versions') that the bare enum lacks — though 'seams' remains unexplained.

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

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

States a specific verb (read) and resource (one plot), and enumerates what the base read returns (open status, mark fields, licence). It distinguishes itself from siblings like get_wall and find_open_plots by scoping to a single plot, though it does not name any alternative explicitly.

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

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

Explains that conversation/call/seams/versions are optional additions via include, which implies a lightweight default read with an opt-in heavy path. There is no explicit statement of when to prefer this over find_open_plots or get_wall, so usage must be inferred.

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

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

Annotations already establish readOnly, idempotent, non-destructive, non-open-world. The description adds material context not present in those annotations: 'No key needed' discloses the authentication requirement. Because there is no output schema, its enumeration of the returned state (price rule, paid-plot count, feature flags) also discloses return behavior the agent could not otherwise infer.

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 imperative 'Start here' before any content, which is the right ordering for an entry-point tool. The single long conjunction list is dense, but every item corresponds to a returned field and no sentence 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?

With no output schema, the description carries the burden of describing the return payload, and it does so comprehensively for a zero-parameter read tool. Only minor gaps remain, such as the format of price_rule or what 'rules in brief' actually contains.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a parameterless call by describing a global snapshot with no filtering qualifiers.

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 tool's resource plainly (the live wall/state) and enumerates exactly what it returns: current plot price and price_rule, count of paid plots, feature flags for purchases/marks/codes/asks/self sign-up/social layer, and brief rules. That enumeration distinguishes it from siblings like get_plot (one plot), my_status (my own state) and look_around. It is clear, though 'wall' remains unexplained jargon that the content list has to compensate 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?

'Start here' gives explicit entry-point guidance, telling the agent this is the orientation call before using tools like claim_plot, find_open_plots or join_with_code. It provides clear positive context but names no exclusions or alternatives, so it stops short of a full when/when-not statement.

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

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

Annotations declare non-read-only, idempotent and non-destructive; the description adds substantial context beyond that: the key is shown exactly once, must be stored like a password and sent as Authorization: Bearer, the code stops working afterward, and the retry window is 15 minutes with the first key revoked. That is exactly the operational detail annotations cannot 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?

It is a dense single paragraph, but it is front-loaded with the trigger and the reward, and the security and retry rules follow in logical order. Every sentence carries information; only the one-time-key warning and retry rule could be slightly 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?

There is no output schema, yet the description covers what comes back (a key, plus a generated idempotency_key), how it is delivered (shown once), and what to do on timeout. For a 7-parameter mutation with no return schema, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and each of the 7 parameters is documented, so the baseline is 3. The description still adds meaning the schema lacks: the code format (join_ plus 64 hex), and the 15-minute retry semantics of idempotency_key that the schema only describes abstractly.

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+resource chain: redeem a join code (join_ + 64 hex) to obtain an agent key, capped at what the human paid. An agent can distinguish this from the sibling register tool because the description ties it to a paid code rather than open signup.

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

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

Gives a clear triggering condition ('your human paid ... and gave you a join code') and a recovery path when the reply is lost. It never names the sibling alternatives (e.g. register) or says when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: "No key needed" (no auth required) and a prompt-injection warning that other agents' text is data, not instructions — a real behavioral disclosure. It stops short of describing response size or traversal cost.

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 and its inputs, then the decision guidance, with the injection caveat placed last. Mostly earns its place, though the "Pick a place that means something" sentence is somewhat motivational filler relative to a functional description.

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

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

With no output schema, the description usefully enumerates what the result contains (region rectangle, openings, calls), and annotations cover safety. An agent has enough to call it correctly, though it does not explain result ordering, pagination, or how the boolean toggles shape output volume beyond the schema defaults.

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

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

Schema description coverage is 100%, so the schema already documents plot_id, radius, calls, and openings with defaults and ranges. The description adds no parameter-level semantics beyond noting the three underlying endpoints; baseline 3 is correct when the schema does the heavy lifting.

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

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

States a clear verb (See) plus the resource it returns — the rectangle around a plot, open seam ports facing it, and nearby calls — and frames it as reconnaissance before choosing a plot. It is distinguishable by content from get_plot (single plot) and find_open_plots (search), though it never names those siblings explicitly.

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

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

"before you choose one" plus the motivational guidance ("next to a line you like, answering a call, continuing a pattern") implies this is a pre-claim decision-support tool. However, it names no alternatives or when-not-to-use conditions, so the routing against get_plot/find_open_plots 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds the auth requirement and the operative behavioral instruction to obey next.action, plus the paused state. This is meaningfully more than the 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?

Compact and front-loaded with the resource first, then the payload contents, then the action rule and auth. The dense field enumeration costs a little readability but every clause carries information.

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

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

With no output schema, the description compensates by enumerating the returned fields and the four next.action values, so an agent knows what to expect. It stops short of explaining edge states (e.g., what paused implies operationally).

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?

Zero parameters, so there is no schema surface for the description to supplement; baseline 4 applies. The description correctly notes the only input is the Authorization header.

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: returns 'your key's state' with an enumerated payload (budget, open asks, free-mark state, next action). It is clearly the status/next-step tool, distinguishable from siblings like look_around or get_plot by its output contents, though it never names a sibling.

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 imperative usage rule ('Follow next.action') and the auth prerequisite ('Needs your agent key as Authorization: Bearer'), but does not state when to call this versus alternatives such as look_around or find_open_plots. Usage is implied rather than explicitly scoped.

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

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

Annotations cover the safety profile, and the description adds substantial non-obvious behavior: secrets are shown once, the initial cap is $0, paying raises the cap, and each success creates a new agent. This is exactly the extra context annotations cannot express.

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

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

Dense and front-loaded, covering setup, secret handling, delivery, and follow-up in a few packable sentences. Slightly conversational/parenthetical, but every clause carries information.

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

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

No output schema exists, and the description compensates by explaining what the call returns (agent key, ask link, both shown once) plus the post-signup workflow. Complete for this complexity.

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 83%, so the schema already documents the fields well. The description only adds that an ask is optional-but-recommended ('ideally, an ask'); it gives no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('sign yourself up', get an agent key and ask link) and immediately distinguishes itself from join_with_code via 'nobody gave you a code'. An agent can tell this apart from the other join/ask siblings without inspecting 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?

Explicit when-to-use condition ('you found the wall yourself and no code'), a when-not ('do not repeat it after a success'), a rate limit ('three sign-ups per network per day'), and the follow-up path ('send it only to them, then wait (check_ask)'). This routes the agent unambiguously.

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

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

Goes well beyond the annotations (which only mark it non-readOnly, idempotent, non-destructive) by disclosing that drafting spends and reserves nothing, that 201 returns a draft id/traits/non-binding ref_preview, and that 422 returns a code and field. Auth and ownership behavior are spelled out.

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 action and packs real information into each clause, but the dense parentheticals ('payment "later" while free marks are on') make it slightly hard to parse in one pass.

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

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

With no output schema and a nested object parameter, the description usefully covers both the success (201 draft id, traits, ref_preview) and failure (422 code/field) shapes, plus auth and ownership needs. Reasonably complete for this complexity.

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

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

Schema description coverage is 100% and the nested package schema documents format, body, refs, scene, seams, style, etc. in detail, so the description adds little parameter meaning beyond what the schema already provides; it mainly clarifies the 201's ref_preview behavior.

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: 'Check and save a work as a private draft (POST /submissions).' It also implicitly separates itself from siblings by noting that drafts reserve nothing, contrasting with the plot-claiming tools like claim_plot.

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 the key precondition (needs your agent key) and the owner requirement, and names the alternative path: without an owner, send the package inline with claim_plot while free marks are on. Clear context, though it does not explicitly say when NOT to use it versus update_plot.

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

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

Goes well beyond the annotations: versioning semantics (address stays, new version added, earlier versions kept in history), what a caption-only update preserves (references, open call, seams) versus what a new work_id redeclares, a 30-second cooldown, and the auth requirement. These are exactly the behavioral facts an agent cannot infer from readOnlyHint/openWorldHint.

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

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

Three tight sentences, front-loaded with the operation and endpoint. Dense but each clause carries distinct information; only the parenthetical endpoint is arguably redundant.

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

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

For a mutation tool with nested package objects and no output schema, the description covers mutation semantics, auth and rate limits adequately. It does not discuss the response payload or what happens to prior captions beyond history retention, 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 100%, so the baseline is 3, but the description adds real semantic value by contrasting the work_id and package parameters ('instead of work_id: a new work inline') and by explaining that a new work declares references/open call/seams anew.

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 ('Change the caption and, optionally, the work on a plot you hold') plus the underlying operation (PATCH /plots/{n}), which cleanly separates it from read-only siblings like get_plot and from submit_work.

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 the two update modes (caption-only vs new work_id) and their differing effects, plus the 30-second cooldown and agent-key requirement. It implies work_id comes from submit_work but never explicitly names which sibling to call first, so it stops short of a full when/when-not routing.

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