Excaliself

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write/repeatability profile is already known; the description adds meaningful behavior beyond that — the hard 500-element cap, that classDef/class are silently ignored, that non-flowchart Mermaid types are rejected, and that the response is a link. It does not mention permissions or what happens on failure.

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 front-loaded with purpose and return value, then breaks into labeled blocks (Elements, Mermaid, Colors) that each carry non-redundant information. It is dense and runs long, but no sentence is filler; the color list is borderline padding but serves a real aesthetic purpose.

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 a nested oneOf schema, six parameters and no output schema, the description covers the schema's hard edges (auto-layout vs manual coordinates, element vs Mermaid mixing, limits, ignored Mermaid directives) and states the return value. An agent has everything needed to compose a valid call.

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 67% schema coverage the description must carry weight, and it does for the hardest part: element types, connector 'from'/'to' vs 'start'/'end', automatic sizing and label wrapping, palette suggestions, and direction semantics. The plain parameters (name, space, folderId) get no description-level elaboration, though folderId and space are already documented in the schema.

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

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

The first sentence states a specific verb and resource ('Creates a NEW drawing from simple elements and/or a Mermaid flowchart') plus the return value ('returns its link'), and immediately scopes it against mutation of existing drawings. The agent can tell this apart from read_drawing and move_drawing 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?

It gives concrete selection guidance: prefer auto-layout and only supply x/y for grids or timelines, and elements and Mermaid may be combined in one call. What's missing is any explicit routing to siblings, such as using list_folders before folderId (that only appears in the schema) or which tool to use to edit an existing drawing.

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 this is a non-read-only, non-destructive, non-idempotent write, so the bar is lower. The description usefully adds that folders can be top-level or nested, but with idempotentHint=false it does not warn that repeated calls create duplicate folders, nor does it mention permissions or what the call returns.

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, front-loaded with the core action and placement, with no redundant or filler wording.

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 simple three-parameter creation tool with annotations and no output schema, the description is nearly sufficient. The notable gap is that it never indicates whether the new folder's identifier is returned, which an agent needs in order to chain into create_drawing or move_drawing.

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 schema already documents the space/parentId interplay (space ignored when parentId is set). The description echoes the two placement modes but adds no syntax, default, or naming details beyond the schema, so it sits at the baseline.

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

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

The description gives a specific verb and resource ("Creates a folder") plus placement scope ("at the top of a Space or inside another folder"). It implicitly separates the tool from create_drawing/move_drawing by naming them as the way to populate a folder, though it never states a negative boundary.

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 describes the two placement modes and points to create_drawing/move_drawing for the follow-up action, which implies when to use it. There is no explicit when-not guidance (e.g. use an existing folder via list_folders first) and no prerequisites 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior by disclosing default sort order (most recently edited first) and that Space and folder are attached to each result. It does not mention pagination or what happens when limit is exceeded, but for a read-only listing the added context is solid.

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 scope, then ordering, then return shape. No filler and nothing an agent has to re-read.

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?

A simple read-only list tool with zero required parameters, full schema coverage, and safety already carried by annotations; the description covers what it returns and in what order. Only pagination behavior is unaddressed, which is minor here.

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

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

Schema coverage is 100%, so all three parameters (limit, space, folderId) are already documented, including the enum and the list_folders cross-reference. The description adds no meaning beyond "Space and folder" appearing in the output, 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?

The description uses a specific verb and resource ("Lists the drawings") and pins down scope ("you can see"), ordering ("most recently edited first"), and returned fields (Space and folder). It stops short of naming how it differs from search_drawings, which is the closest sibling, so an agent must still infer the browse-vs-search split.

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 drawings you can see" implicitly frames this as an unfiltered browse-all operation, which suggests search_drawings is for targeted lookup, but that contrast is never stated. No exclusion, no prerequisite, no guidance on when the filters make it the wrong choice.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds genuine context that results are permission-scoped ('you can see') and that each entry carries Space and path. It does not disclose pagination, ordering, or result-size limits, so credit is partial rather than rich.

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

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

A single front-loaded sentence with no wasted words; the return-field hint is attached compactly. It is efficient, though extremely terse for a tool with sibling alternatives.

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 simple, parameterless-optional list tool with no output schema, the description adequately conveys scope and returned fields. Gaps remain around pagination, ordering, and how it differs from the drawing-list siblings, so it is complete only at a minimum-viable level.

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 single 'space' enum is documented as 'Only this Space.', so the schema already carries the parameter meaning. The description never mentions the space filter and adds nothing beyond the schema, making baseline 3 appropriate.

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

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

Names a specific verb ('Lists') and resource ('folders') and adds scope ('you can see') plus the returned fields (Space and path). The resource distinction from list_drawings/search_drawings is clear from the name and description, though it never explicitly contrasts with those siblings.

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

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

There is no when-to-use guidance: nothing says when to use list_folders versus list_drawings or search_drawings, whether results are paginated, or whether the space filter is required for narrower results. Usage must be inferred from the tool name 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description usefully clarifies that omitting the folder target relocates to the top of the Space and that a move is confined to one Space. It says nothing about what happens to the drawing's previous placement, required permissions, or why the call is non-idempotent.

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 with zero filler; the destination behaviour leads and the Space restriction follows as the qualifying constraint.

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

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

For a two-parameter move tool with full schema coverage, no output schema, and annotations covering the mutation profile, the description supplies what is needed to call it correctly. Only permission requirements and the effect on the source location remain unstated.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema: folderId must resolve to a folder inside the drawing's own Space, a constraint the schema does not state. The 'leave it out' destination semantics are duplicated from the schema rather than extended.

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 (moves) and resource (drawing) plus both destination modes (into a folder, or to the top of its Space). The distinction from siblings like create_drawing, trash_drawing, and restore_drawing is immediately obvious.

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 precondition: the target folder must belong to the drawing's Space, and cross-Space moves are impossible. It does not name alternatives or say when to prefer this over e.g. create/trash, but the operating context is 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?

The readOnlyHint annotation already covers the safety profile, so the bar is lower, and the description still adds meaningful context by characterizing the returned representation as a semantic description rather than raw JSON. With no output schema, that single sentence carries the whole burden of explaining return shape, and it does so well; it omits edge behavior for missing or very large drawings.

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

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

Two sentences, front-loaded with the primary statement of what is returned, then a short exclusion clause. No filler, no restating of the tool name or 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 one-parameter read tool with no output schema, the description does the essential work of telling the agent what the response contains. Remaining gaps are minor: no mention of failure behavior for an invalid id or of truncation on very large drawings.

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 sole parameter's schema text already explains that the id comes from list_drawings or search_drawings. The description adds no further meaning about the id (format, behavior on unknown ids), so the baseline of 3 applies.

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

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

The description gives a specific verb (describes) and resource (a drawing) and enumerates exactly what is returned: shapes, labels, text, arrow connections, containment, and positions. The closing 'Not the raw Excalidraw JSON' usefully differentiates it from a raw-fetch alternative, though no sibling tool is named explicitly.

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

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

Usage is only implied: the reader infers it is the tool to call when you need a drawing's content. There is no explicit 'use this after list_drawings/search_drawings' routing in the description (that hint lives only in the id parameter's schema text) and no statement of when not to use it, such as for listing or searching.

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 that this is a non-read-only, idempotent, non-destructive mutation. The description adds genuinely non-obvious behavior the annotations cannot express: restoration to the original folder, and the fallback chain to the nearest ancestor folder or top level when that folder is gone. What's missing is failure behavior for a drawing that isn't trashed.

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, front-loaded with the primary action and followed by the edge-case outcome. Every clause carries information; nothing is redundant with the title or schema.

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

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

For a one-parameter mutation with no output schema, the description covers the action, the precondition, and the folder-fallback semantics well. It omits error/return behavior, a minor gap given how simple the tool is.

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 is a single parameter with 100% schema description coverage ('The id of a trashed drawing.'), so the schema already carries the semantics. The description adds nothing about the id beyond the trash precondition, which matches the baseline 3.

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

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

The description names a specific verb and resource ('takes a drawing out of the trash') and implies the trash-to-folder transition, which cleanly separates it from restore_folder. It stops short of explicitly naming siblings, but the resource noun makes the distinction obvious.

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

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

Usage is only implied through the precondition that the drawing is in the trash. There is no explicit statement of when not to use it, nor a pointer to trash_drawing/restore_folder as alternatives, so the agent must infer 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?

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation. The description adds genuinely new behavior beyond that: the cascade of trashed children and the fallback placement when the parent folder is gone. It still omits error behavior for an invalid or non-trashed id, so it falls short of fully transparent.

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 filler, with the core action front-loaded and the edge-case relocation behavior second. Nothing could be removed 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 single-parameter mutation with no output schema, the description covers the action, the cascade effect, and the notable parent-missing edge case. Only failure modes (invalid id, folder not in trash) and any conflict-renaming behavior are left unstated, which are 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 coverage is 100% and the single parameter is already documented as 'The id of a trashed folder', which the description merely echoes. No added detail on id format, where to obtain the id, or whether ids from other endpoints are accepted, so baseline 3 applies.

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

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

States a specific verb (restore) and resource (folder) plus the scope of the operation — the folder comes back with everything that was trashed alongside it. The folder-versus-drawing distinction from the sibling restore_drawing is unambiguous from the description text itself.

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

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

Usage is implied by 'takes a folder out of the trash', so an agent can infer this applies to trashed folders only. There is no explicit when-not guidance, no mention of prerequisites or an alternative tool (e.g. what to do for drawings or for permanently deleted items).

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?

readOnlyHint=true already establishes the safety profile, so the description's job is to add context — and it does: AND-semantics across all query words, case-insensitive matching, name matches ranked first, and a text snippet around each match. What's missing is any note on result count behavior or what happens when no drawing matches.

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 tight sentences with zero padding; the matching rule comes first and the result-shape detail second. Every clause carries information an agent would otherwise have to guess.

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 three-parameter search with no output schema, the description supplies the ranking rule and the result shape (snippet around the match), which is the key unknown. It leaves the space filter and limit semantics to the schema, which is acceptable given their low 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?

At 67% schema coverage the schema already documents limit and space, but the description adds genuine meaning for the undocumented query parameter: all words must match, matching is case-insensitive, and both name and body text are searched. It says nothing about the space enum or limit bounds beyond what the schema states, so it adds value on one param and not the other two.

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?

"Finds drawings whose name or text contains every word of the query" gives a specific verb (finds), resource (drawings) and match surface (name or text), which distinguishes it from list_drawings by implying content-based lookup. It stops short of explicitly contrasting itself with the listing siblings, so an agent must infer that distinction.

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

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

Usage is implied: the phrase "every word of the query" signals a multi-term search, and the mention of name-vs-text matching hints at when this beats a plain listing. There is no explicit "use this instead of list_drawings when..." statement, no note on empty/all-word behavior, and no guidance on narrowing with the space filter.

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 idempotentHint=true, so the safety profile is covered. The description still adds real value beyond them: a 30-day restore window, permanent deletion afterward, and the Team-scoped consequence that every member loses the drawing. It omits permission/auth requirements and whether an already-trashed drawing can be re-trashed.

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 with zero filler, front-loaded with the action and then the consequences. Every sentence—effect, restore window, Team impact—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?

For a one-parameter destructive tool with strong annotation coverage and a documented lifecycle (restorable for 30 days, then permanent), the description is nearly complete. Minor gaps remain around who may trash a drawing and behavior on already-trashed items.

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 id parameter already documents its source (list_drawings or search_drawings). The description adds no format or constraint detail about the identifier, so the schema is doing all the work and 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?

"Moves one drawing to the trash" gives a specific verb and resource, and "one" scopes it as a single-item operation, implicitly separating it from trash_folder. It never names a sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by the effect described (this is the delete path) and the mention of restore implies restore_drawing is the reversal, but the description never states when to pick this versus move_drawing or trash_folder. An agent can infer intent but gets no explicit routing or prerequisite guidance.

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

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

Goes well past the annotations, which only say destructiveHint=true and idempotentHint=true. The description discloses the cascade scope (subfolders and all drawings), the 30-day restore window treatable as one unit, permanent deletion afterward, and that a Team folder disappears for every member — exactly the blast-radius facts an agent needs before a destructive 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 tight sentences with the destructive action front-loaded, followed by recovery and permanence, then team impact. The fragment "In Team, every member loses it" is slightly clipped but earns its place by conveying a high-stakes consequence.

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 destructive tool with no output schema, everything material is covered: what is trashed, what comes with it, how long recovery is possible, when it becomes permanent, and the multi-user consequence. No output schema exists, so no return-value explanation is owed.

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 id parameter already documents that it comes from list_folders, so the schema carries the parameter burden. The description adds nothing about id format or validation, which is acceptable but not additive.

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 ("Moves one folder to the trash") and immediately scopes the cascade: subfolders and every drawing inside them. The word "one" plus the folder focus distinguishes it from the sibling trash_drawing, so an agent can pick 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?

Usage is implied by the object being acted on (a folder rather than a drawing), but there is no explicit when-to-use or when-not-to-use guidance, and no mention of restore_folder as the inverse operation. An agent can infer the routing but must do the inference itself.

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