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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real value beyond that: the required write scope, per-account name uniqueness, the 50-collection account limit, and the fact that rename/delete are not available through this call.

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

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

Three short sentences, each carrying distinct information: what it does, the permission and uniqueness constraints, and what it does not handle. Nothing is redundant and the core action is front-loaded.

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

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

For a single-parameter creation tool with no output schema, the description covers the permission requirement, uniqueness and quota constraints, and states that a slug is returned. Nothing an agent needs in order 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 0%, so the description must carry the meaning of the single parameter — it does, explaining that 'name' must be unique per account and is subject to an account-level collection cap. Length constraints remain only in the schema, but the important semantic constraint is stated.

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

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

States a specific verb and resource ('Create an empty collection by name') and adds the scope permission and return value. It is clearly distinguishable from siblings like list_collections and fetch_collection, which read rather than create.

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: write scope is required, names must be unique per account, and there is a 50-collection cap. It also notes that renaming and deleting are handled in the app, which effectively excludes those operations here, though it does not name a sibling alternative for 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?

Beyond the annotations it adds concrete behavior: default visibility is private, a maximum of 10 files, instance/storage limits, files are stored as data only (not executed), and retries can create duplicates. That last point turns the idempotentHint=false annotation into actionable guidance, which is exactly the value the description should add on top of 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?

Six short sentences, no filler, with the write-scope precondition and the default visibility front-loaded before limits and the retry warning. Each sentence contributes a distinct operational fact.

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

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

For a 7-parameter creation tool with no output schema, the description never says what comes back — no mention of a new snippet ID or URL, which an agent needs to chain into read_snippet or update_snippet. It also omits the source and tags parameters entirely, though it does cover the main failure modes well.

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, and it only explains three of seven parameters: files (max 10, data only), collection (must pre-exist), and visibility (defaults to private). It says nothing about title, tags, description, or the nested source object (repository/commit/dirty), leaving meaningful gaps.

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

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

The description opens with a specific verb and resource ('Save code as a new snippet'), and the word 'new' implicitly separates it from update_snippet. It does not explicitly name a sibling, so an agent must infer the boundary with update_snippet rather than being told.

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

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

It states a real precondition ('write scope required', 'A collection must already exist') that tells the agent when the call will fail, and 'Do not retry automatically' is an explicit usage instruction. It stops short of naming update_snippet or create_collection as the alternative path, so the routing is only partially handled.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the bar is lower, yet the description adds real substance: deterministic ordering, a 50-snippet page cap, and the reassurance that nothing is executed. It does not describe error behavior for a bad slug or expired cursor, 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?

Four tight sentences, front-loaded with what is returned and scoped immediately after by ordering and page size. Nothing is redundant, though the cursor naming mismatch adds a small parsing burden.

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 appropriately describes the shape of the return (page of numbered steps with full snippet files, up to 50, plus continuation tokens). The only meaningful gap is that the required 'slug' parameter's meaning is never stated.

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, and it only partly does. It explains continuation flow, but refers to 'nextCursor' and 'nextStep' rather than the actual parameter names 'cursor' and 'startStep', and never explains what 'slug' identifies or its naming constraints.

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 ('Fetch a page of your collection') plus the exact output form ('numbered recipe steps, with full snippet files'), which cleanly separates it from siblings like list_collections and search_snippets. The closing note that it 'does not execute the recipe' further disambiguates intent.

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: ordering is oldest-capture-first, pagination continues via cursor/step, and the call is non-executing. It stops short of naming an explicit alternative (e.g., when to prefer list_collections or search_snippets instead), so it is strong but not exhaustive.

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 non-destructive behavior, so safety is covered. The description adds genuinely new behavior (result ordering is oldest-first, and counts are of live snippets), but says nothing about whether the list is complete or paginated, which matters for a listing tool.

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

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

Two short sentences, zero padding, with the result shape front-loaded ahead of the downstream usage note. 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 usefully enumerates the returned fields and ordering, and the annotations carry the safety profile. The only omission is any statement about result completeness or size limits, which is minor for a zero-parameter list tool.

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

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

The tool takes no parameters and the schema coverage is trivially 100%, so there is nothing for the description to disambiguate. Baseline applies; the mention of the slug as the downstream input is a small bonus.

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

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

States a specific verb and resource (list collections) plus the ordering (oldest first) and the exact fields returned (slug, name, live snippet count). It is clearly distinct from fetch_collection, which retrieves a single collection by slug, and from the snippet-oriented 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?

Makes the tool's role in the workflow explicit: call it to obtain slugs, which are then consumed by create_snippet, update_snippet and fetch_collection. It does not state exclusions or name alternatives for the case where the slug is already known, so it falls just 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 already declare readOnly, idempotent, non-destructive and closed-world, so the description's job is lighter. It still adds real signal: the word 'live' implies trashed or deleted snippets (see trash_snippet) will not resolve, and it enumerates what comes back (files, paths, code, source metadata). It does not cover failure behavior for unknown or trashed IDs.

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

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

One sentence, front-loaded with the verb and resource, with the return contents appended as a useful clause. There is no filler or redundant restatement of the title.

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

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

With no output schema, the description responsibly summarizes the return payload, and it clearly frames the tool as a single-item read. The main residual gap is not stating what happens when the ID is invalid or the snippet is trashed.

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% and the single parameter is named only 'id' with a character pattern, so the description carries the burden. It adds meaningful semantics by stating that a slug is also accepted, which the schema does not reveal, though it gives no format or precedence guidance when both forms could apply.

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 ('Read one of your live snippets') and scopes it to a single item fetched by 'ID or slug', which implicitly separates it from search_snippets and fetch_collection. It stops short of naming a sibling alternative explicitly, so it lands just below the top mark.

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 'by its ID or slug' phrasing implies you should already have an identifier, which steers agents away from this tool for discovery. However, there is no explicit when-to-use/when-not statement and no pointer to search_snippets for resolving an unknown identifier.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts: results are paged via nextCursor and must be re-invoked with that cursor, and the payload contains summaries rather than code. It omits default/max page size behavior, which keeps it at 4.

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 with no filler: capability first, return/pagination behavior second, sibling hand-off last. Every clause carries information an agent needs before calling.

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 six optional parameters, zero schema descriptions and no output schema, the description still conveys what is returned (summaries plus a cursor) and how to paginate, which is the critical missing context. The undocumented limit and the absence of any default page size are the remaining, minor gaps.

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 burden, and it does for most parameters: query (which fields, all-words semantics), tags, language, collection, and cursor (how to use it for the next page). Only limit is left undefined; its name and 1-100 bounds make it largely self-evident, but the omission is a real gap.

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

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

States a specific verb and resource ("Find your live snippets") and then enumerates exactly what is searched: title, description, tags, file paths and code. The word-match semantics ("every word must match") and the phrase "live snippets" further narrow the resource, and the closing sentence separates it from read_snippet.

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 code retrieval to read_snippet ("Use read_snippet to fetch code"), which is the main ambiguity among these siblings. It also warns that matching is conjunctive across words. There is no explicit statement of when not to use it or of a browsing-only alternative, so it falls short of a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful context on top: the snippet link stops working, the owner can restore it from the app until the trash is emptied, and the operation is never permanent. It also surfaces the authorization requirement (write scope) and a confirmation step, which 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?

Three short sentences, front-loaded with the action, then reversibility, then the safety instruction. No sentence repeats the name or the annotations, and nothing is padding.

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

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

For a one-parameter mutation with annotations present and no output schema, the description covers side effects, reversibility, scope requirements, and confirmation guidance. The only omission is what the call returns or whether the response includes the trashed state, which is minor at 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 0% and the single parameter 'id' is never described in the text, so the description adds no meaning beyond the schema's type and pattern constraints. The gap is small because a lone 'id' on a snippet-trashing tool is self-evident, but it is still undocumented.

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

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

The description opens with a specific verb and resource ('Move your live snippet to the trash') and immediately constrains scope by stating it never deletes permanently, which separates soft-delete semantics from any hard-delete expectation among the snippet/collection 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?

It gives concrete preconditions for use: write scope is required and the agent should confirm with the user first. What it lacks is an explicit pointer to an alternative when permanent removal or bulk cleanup is actually wanted, leaving that branch 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 flag destructiveHint=true and idempotentHint=false, and the description adds real context on top: write scope required, the full file list is overwritten rather than merged, omitted fields are preserved, explicit null clears collection/source, and an edit is recorded in history. The history note also explains why the call is non-idempotent despite replace semantics.

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

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

Four short sentences, front-loaded with the destructive replace action, then the mitigation (read first), then the field-by-field preservation rules. No filler and no repetition of the title.

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

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

For a destructive 8-parameter mutation with no output schema, this covers the important ground: permissions, overwrite breadth, preservation, null semantics, and history. It does not say what a successful response contains or whether files[].lines can be used for partial-file updates, a minor gap given the destructive hint.

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 and largely delivers: it names every optional field (description, visibility, collection, tags, source), states the preserve-by-default rule, and defines explicit-null clearing for collection and source. Only the nested shapes (files[].lines, source.commit/dirty) are 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?

"Replace the title and entire file list of your live snippet" gives a specific verb (replace) plus the exact resource and scope, and the closing sentence about link/expiry/password/burn settings makes clear this is not the settings-update sibling. An agent can distinguish update_snippet from update_snippet_settings and create_snippet 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?

"Read it first to keep files you still need" is an explicit prerequisite directing the agent to read_snippet before calling, which is exactly the right routing for a replace-semantics tool. It stops short of naming update_snippet_settings as the alternative for the fields this tool leaves untouched, so the exclusion is implied rather than stated.

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint=false) by disclosing the write scope requirement, that expiry is counted from now, that null removes the password, that omitted fields are preserved, that a set password becomes visible in the conversation, and that the password is never returned. These are exactly the consequences an agent needs before mutating sharing state.

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

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

A single dense paragraph that front-loads the purpose, then behavioral consequences, then the confirmation requirement, then the return contract. Every clause carries information; nothing is redundant.

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

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

For a destructive mutation tool with no output schema, the description covers permissions, patch semantics, irreversible effects, the human-confirmation step, and what the response contains. An agent has everything needed to call it safely and interpret the result.

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

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

With 0% schema description coverage, the description carries the load and mostly succeeds: it explains expiry semantics ('counted from now'), password null-removal, burn-after-read, and the omit-to-preserve rule for all five fields. It does not restate the enum values for visibility or expiry, but those are visible in the schema, so the remaining gap is small.

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 — changing who can open a live snippet — and enumerates the exact settings covered (visibility, expiry, password, burn after read). This makes it clearly distinct from the sibling update_snippet, which handles snippet content rather than sharing scope.

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

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

Gives conditional guidance: confirm with the user before making a snippet public or setting a password, and states that omitted fields remain unchanged, which implies partial-update usage. It does not explicitly route the agent between this and update_snippet, but the scoping sentence makes the boundary reasonably clear.

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