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

Adds substantial behavior beyond the annotations: the key is written into the chat transcript, a required consent flag gates the call, the result is persisted to ~/.marketplace-mcp/cabinets.json with chmod 600, and the value is never echoed. It also discloses side effects the annotations don't cover — the name falls back to the real shop name fetched from the marketplace, then to 'main'.

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

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

The warning is front-loaded before the Args block, and each section earns its place: safety notice, parameter semantics, storage location. The unrendered brace placeholders and a couple of redundant restatements (the consent flag appears in both the warning and the Args) cost it a point.

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 3-parameter mutation tool with nested objects and an output schema, this covers what the schema cannot: consent gating, where the secret is written, that it is not echoed, and how the cabinet gets named. Return values are correctly left to the output schema.

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

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

Schema coverage is 0%, so the description carries full burden and mostly succeeds: it documents the per-service credential shape with concrete examples (Ozon client_id/api_key, WB token), the optional name and its fallback chain, and the mandatory consent flag. The literal unrendered template markers ('{fields}', '{{"client_id"...}}') are a defect that leaves the exact required-field list ambiguous.

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 ('Add or update a cabinet') and immediately defines what a cabinet is (a named set of API credentials), which cleanly separates it from diadoc_list_cabinets, diadoc_remove_cabinet, and diadoc_use_cabinet. The only friction is the naming mismatch: the tool is prefixed diadoc_ and sits among Diadoc document tools, while the body talks about Ozon/WB marketplace credentials, which could momentarily confuse selection.

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 use context ('from chat') and an explicit when-not with a named alternative: 'the safe alternative is the installer (install.py / double-click), where the key never enters chat.' That is genuine routing guidance. It stops short of contrasting with the other credential-adjacent siblings (diadoc_set_key, diadoc_use_cabinet), so the agent still has to infer which key-entry path applies.

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

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

Goes well beyond the annotations by spelling out the confirmation protocol: read endpoints fire immediately, writes need confirm_write=true, destructive calls need both confirm_write and i_understand_this_modifies_data, and 'nothing is sent otherwise.' That last clause is a critical safety behavior an agent could not infer from destructiveHint=true alone.

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?

Behavioral gating is front-loaded before the parameter list, and the Args/Returns blocks are compact with no redundant prose. Every line adds information an agent needs to invoke the tool correctly.

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

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

For a high-complexity generic dispatcher it covers the safety model, every parameter, and the error envelope (an output schema also exists, so return details are redundant-safe). The only real gap is sibling disambiguation against call_raw/fetch_all and how paginated results should be handled.

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 does: it documents all six parameters including placeholder semantics for path_values, query-string vs JSON body, and the exact conditions under which each confirm flag is required. This is exactly the compensation a 0%-coverage schema needs.

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 ('Execute one catalog endpoint by operation_id') and points at diadoc_search_methods as the source of valid ids. It does not, however, distinguish itself from diadoc_call_raw or diadoc_fetch_all, which an agent could easily confuse with a generic dispatcher.

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 operational workflow: obtain the operation_id from the catalog (search_methods), then call it, with explicit gating rules for write and destructive endpoints. It never states when to prefer a sibling such as diadoc_call_raw or diadoc_fetch_all, so alternative-routing guidance is absent.

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 readOnlyHint=false/destructiveHint=true, and the description adds real nuance beyond them: safety is inferred from the HTTP verb (GET=read, POST/PUT/PATCH=write, DELETE=destructive) and the confirmation gating via confirm_write / i_understand_this_modifies_data. It does not contradict the annotations, though it could say more about host-override side effects or rate limits.

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 key capability, then uses a clean Args block and a one-line Returns summary. Every line carries information; only the bracketed {svc}_call_method reference is slightly opaque.

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, open-world raw-call tool the description covers verb-based safety, confirmation flags, all params, and the return envelope (aligning with the output schema). It is largely complete, missing only authorization/permission expectations.

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

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

With 0% schema description coverage, the description compensates well by naming every parameter (method, path, host, query, body, both confirmation flags) with brief meaning and a path format example. It adds only light semantics for host override and query/body shape, so not a full 5.

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

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

States a specific verb and resource ('Execute ANY endpoint') and explicitly scopes it as raw access covering endpoints 'not in the catalog', which cleanly differentiates it from diadoc_call_method and diadoc_describe_method. An agent can identify the tool's role 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?

The 'even ones not in the catalog (full API coverage)' phrasing implies when to reach for this raw tool over catalog-based calls, and it references the confirmation rules of {svc}_call_method. It stops short of an explicit when-not/alternative rule (e.g., 'prefer diadoc_call_method when the method is cataloged').

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 and openWorldHint=false, so safety is partly covered. The description adds genuinely useful context beyond that: it explicitly does not reveal secret values and only reports which variables are set, which tells the agent the output is safe to log or surface.

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

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

Three short lines: purpose first, the security caveat second, return shape last. Every sentence carries information and there is no filler.

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

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

For a no-argument check tool with an output schema, the description is nearly complete. The only soft gap is that it doesn't say which credentials/variables are considered 'required' or where they come from, though the returned 'required' array largely covers this.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly adds nothing about inputs because there are none.

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 (check) and resource (required credentials in the environment), and scopes it clearly against siblings like diadoc_set_key, which mutate credentials rather than inspect them. An agent can tell instantly this is a read-only preflight check.

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 purpose implies it is a preflight check before calling authenticated methods, but the description never says when to run it, when it can be skipped, or how it relates to diadoc_set_key / cabinet selection. Usage is inferable 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing this as a safe local catalog read, and the description does not contradict them. The description adds the record's composition (scope, safety level, pagination, rate limit), which is useful, but since an output schema exists this mostly restates return content rather than adding deeper behavioral context.

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

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

A single front-loaded sentence that names the action first and then lists the record fields. No repetition or 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 an output schema present and annotations covering the safety profile, the description needn't explain return values or side effects. It is nearly complete; the only omission is where operation_id comes from, though sibling discovery tools imply the workflow.

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% for the single required operation_id, so the description carries the interpretive burden. It clarifies that operation_id identifies 'one endpoint' of the catalog, which adds some meaning, but gives no format, source, or example for the identifier.

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 (return) and resource (full catalog record for one endpoint) and enumerates exactly what the record contains. An agent can distinguish it from siblings like diadoc_search_methods or diadoc_get_section, though the description never explicitly contrasts them.

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 tool takes an operation_id and returns details for that single endpoint, so an agent can infer it is a lookup step after discovery. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. search_methods).

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 the safety profile (readOnlyHint), so the description's job is to add behavior — and it does: it handles offset, last_id, cursor (Ozon v4/v5), page and WB lastChangeDate styles, manages cursor fields itself, and caps results at max_items (default 10000) with a 'truncated' flag. That is substantive context an agent would not get from annotations alone, though it doesn't discuss rate limits or partial-failure behavior mid-pagination.

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 behavior in sentence one, then mechanism, then a clean Args list and a compact Returns line — no filler. The Args block slightly restates names the schema already carries, but overall it is tight and well ordered.

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 an output schema present and a Returns line naming {ok, items, total_fetched, pages_fetched, truncated}, return semantics are well covered. For a 7-parameter tool spanning multiple pagination conventions, the description addresses purpose, parameters, and outputs adequately, though deeper guidance on edge cases (e.g., what happens when the endpoint is not paginated) is absent.

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 its Args block defines all seven parameters: operation_id (must come from the catalog), query/body/path_values as base params with cursor fields managed, items_path as an override, limit as page size, and max_items as a hard cap. The query/body/path_values group is glossed in a single line, so it isn't fully exhaustive.

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

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

The first sentence states a specific verb+resource+scope: 'Auto-paginate a read endpoint and return every row in one response.' An agent immediately understands this fetches the full result set rather than one page. It does not explicitly name or contrast with sibling tools like diadoc_call_method/diadoc_call_raw, so it stops short of the top band.

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: it is for 'a read endpoint from the catalog' when you want all rows, and max_items is framed as protecting context. But there is no explicit when-to-use/when-not guidance and no direction on choosing this over diadoc_call_method or diadoc_call_raw, so the agent must infer the 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 readOnlyHint=true and openWorldHint=false, and the output schema already defines the returned fields, so the description's enumeration of {operation_id, method, path, safety, summary} largely repeats structured data. It adds nothing about ordering, pagination, or size limits that isn't already covered elsewhere.

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

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

Front-loaded with the core action in the first sentence, followed by a compact Args and Returns block. Slightly boilerplate but every line is short and no sentence is wasted.

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

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

For a simple single-parameter read tool, the description covers the argument source and the safety profile is carried by annotations and return shape by the output schema. Only the absence of any usage routing between sibling discovery tools keeps it short of full completeness.

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 single parameter — and it does, naming it as a 'section name', pointing at the sibling that enumerates valid values, and giving a concrete example ('statistics'). That meaningfully compensates for the empty schema.

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

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

States a specific verb and resource: lists all endpoints belonging to one section. This is distinguishable from the sibling diadoc_list_sections (which lists the sections themselves), though the description never explicitly names that contrast.

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 implies a discovery workflow by pointing to {svc}_list_sections for valid section names, but gives no when-to-use guidance relative to alternatives such as diadoc_search_methods or diadoc_describe_method, nor any exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that with the 'Secret values are never returned' guarantee, a behavioral trait an agent otherwise couldn't 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-loads the purpose, then the return shape, then the secret-handling caveat in three tight sentences. Slight redundancy in restating the return structure that the output schema already carries.

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 an output schema present, return values need not be explained in depth, and with zero params and read-only annotations the burden is low. The description is sufficient, though it could note where active-cabinet selection feeds into subsequent calls.

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 nothing for the description to disambiguate; baseline 4 applies. The description cannot and need not add parameter meaning here.

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

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

States a specific verb and resource ('list configured cabinets') with additional scope ('for this marketplace and which one is active'). An agent can tell this is the read-side counterpart to use/remove/add_cabinet siblings, though the description never names them 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 — one would call this to discover cabinets before diadoc_use_cabinet, but the description gives no explicit when-to-use, prerequisites, or named alternatives. It offers no exclusions either.

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 and openWorldHint=false, so safety and scope are covered structurally. The description adds only that each section is annotated with its catalog endpoint count, which is useful shaping but not non-obvious behavior beyond the output schema.

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

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

A single short sentence that front-loads the action and resource, with the endpoint-count detail appended. No filler or redundancy.

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

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

For a zero-parameter read-only listing with an output schema, the description covers what the tool returns at a high level and needs no return-value documentation. The only shortfall is the absence of any routing guidance among the many sibling tools.

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 the baseline is 4 and there is nothing for the description to clarify about inputs. No syntax, defaults, or formats are needed.

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 (list) and resource (API sections) and clarifies the payload includes an endpoint count per section. It is clear on its own, but it never names or contrasts with the obvious sibling diadoc_get_section, so the agent must infer the 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 only implied: the tool is a browsing/list operation and the description hints at a discovery role by reporting endpoint counts, but it does not say when to reach for this versus diadoc_get_section or diadoc_search_methods, nor mention any prerequisites.

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 and openWorldHint=false, so safety is covered. The description adds the useful trait that this is a navigation/orientation call and that it can be invoked with zero arguments to get a global view, which goes beyond the annotation data.

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

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

Front-loads the core purpose, then the two invocation modes, then the routing advice — efficient ordering with minimal waste. The parentheticals and quoted asides are slightly loose but do not obscure the signal.

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 an output schema present, return values needn't be described, and the description covers purpose, invocation modes, and the parameter. For a simple one-param navigation tool this is nearly complete; only sibling-relative routing guidance is absent.

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 burden and does so well: it explains the empty default returns the whole map, and gives concrete entity values ('reviews', stocks/prices/orders) plus the effect of passing one. Only a full enumeration or naming rule for valid entity strings is missing.

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 function: an overview map of the API's business entities and the go-to methods for each, with a distinct behavior for the no-arg vs. entity-scoped case. It doesn't explicitly contrast itself with siblings like diadoc_list_sections or diadoc_search_methods, so it falls short of full sibling differentiation.

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 usage context — 'Use this before guessing — it orients you fast' establishes this as a precede-everything orientation step. It does not name alternatives or exclusions (e.g., when to prefer diadoc_search_methods or diadoc_describe_method instead), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and non-readOnly, so the safety profile is covered. The description adds genuine extra behavior beyond the annotations: if the removed cabinet was active, another becomes active. It still omits whether deletion is reversible and whether the active cabinet's replacement is deterministic.

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 the core action and side effect front-loaded, plus a compact Args block. No wasted prose, though the Args line duplicates the parameter name already in the 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?

An output schema exists, so return values need not be described. For a single-parameter destructive tool, the description covers the action and the active-cabinet side effect but omits reversibility and where to source valid names, leaving modest 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 carries the full burden, and "name: the cabinet to remove" merely restates the parameter name. It gives no format, case-sensitivity, or hint about obtaining valid names (e.g. via diadoc_list_cabinets).

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?

Clear verb+resource: "Delete a stored cabinet" tells the agent exactly what happens, and the sibling set (add_cabinet, use_cabinet, list_cabinets) makes the intent unambiguous by contrast. It does not explicitly name a sibling, so it stops short of a 5.

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

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

Usage is only implied — a stored cabinet you no longer need gets removed. Nothing states when to prefer use_cabinet (switching) over remove_cabinet, nor any prerequisites or confirmation requirements. Adequate but with clear gaps.

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 and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the search is bilingual (Russian and English) and results come back ranked best-first. It does not mention pagination or a result ceiling cap, which keeps it out of the top band.

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 one-line purpose followed by a compact Args block; each line earns its place with the exception of the mildly redundant 'Returns JSON list of matching endpoints.' No padding or narrative 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?

An output schema exists, so return structure need not be described, and both parameters are documented against a 0% schema coverage gap. For a low-complexity, flat-schema search tool this is close to complete; only the lack of a next-step pointer to the describe/call siblings is a 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 description coverage is 0%, so the description must supply meaning and it largely does: query is free text with concrete example strings, and limit is given the range 1-50, which the schema omits beyond a default of 15. It does not explain limit's interaction with result ordering, so not a 5.

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

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

States a specific verb and resource: 'Search the endpoint catalog by keyword.' An agent can distinguish it from retrieval siblings such as diadoc_get_section or diadoc_describe_method. It stops short of explicitly naming the sibling it is not, so it misses the top band.

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 'search the endpoint catalog' with example queries, but there is no guidance on when to prefer this over diadoc_list_sections, diadoc_map, or diadoc_describe_method, and no exclusions. Adequate but leaves the routing decision to inference.

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

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

Annotations only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the description adds the substantive traits: the key lands in the chat transcript, a boolean acknowledgement is mandatory, the key is validated against the marketplace on success, the shop name is reported, and the secret is stored locally with chmod 600 and never echoed back. It also flags the security trade-off, 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?

Front-loaded with the purpose, then a warning block, then Args, then success behavior — a sensible scan order with little filler. The unresolved '{fields}' artifact and the mixing of warning prose into the arg list are minor structural blemishes.

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 a security caveat, the definition covers the required acknowledgement, the error mode (key validated against the marketplace), storage location and permissions, and the non-echo guarantee. An output schema exists, so return values needn't be spelled out.

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 coverage the description must carry all meaning, and it documents the cabinet defaulting behavior and the acknowledgement flag well. However, the required nested credentials object is described only as 'dict with the required fields ({fields})' — an unresolved template placeholder, so the agent still cannot learn which fields are required.

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 / rotate the API key') plus the scope ('from chat'), which separates it from siblings like diadoc_add_cabinet and diadoc_use_cabinet. An agent can identify the operation 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 explicit triggers ('the old one expired or leaked'), an explicit alternative ('the safe, terminal-free alternative is the installer, where the key never enters chat'), and follow-up advice (use a scoped key, rotate in the seller cabinet if exposed). This is the when/when-not/alternatives pattern done well.

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=false, idempotentHint=true, and openWorldHint=false. The description adds genuinely useful stateful context beyond those hints: the switched cabinet's credentials become active for all subsequent API calls, which is a global side effect the annotations do not 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?

Front-loaded with the core action and effect in the first sentence, then the parameter note. Two compact sentences with no filler, though the '{svc}' placeholder is slightly ambiguous in a standalone reading.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description supplies the essential effect and the parameter source, leaving only sibling differentiation unaddressed.

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 burden for the single parameter. It explains that 'name' is 'the cabinet to activate' and points to {svc}_list_cabinets as the source of valid values, which meaningfully compensates for the schema 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+resource ('Switch the active cabinet') and its immediate effect ('Subsequent API calls use its credentials'), so the agent knows exactly what the tool does. It does not explicitly name or contrast with siblings like add_cabinet or remove_cabinet, but the purpose is unambiguous.

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

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

Usage is only implied: the description tells the agent to consult {svc}_list_cabinets for a valid name, which is a prerequisite hint, but it never states when to prefer this over add_cabinet, remove_cabinet, or set_key, nor any conditions/exclusions.

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