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

The description surfaces security-sensitive behavior beyond the annotations: the key is placed in the chat transcript, it requires an acknowledgment flag, and the cabinet is saved to a local file with chmod 600 and never echoed. Annotations already declare the tool mutable (readOnlyHint=false) and idempotent, so this extra context elevates transparency.

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

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

The description is usefully structured with a warning, a bullet list-like argument breakdown, and an outcome line. It is a little longer than required, but every sentence earns its place by documenting the risk, the parameters, and the safe storage behavior.

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?

Given the output schema exists, the description doesn't need to explain return values. It covers the side effects (file, permissions, chat transcript), parameter nuances, and the required consent flag. Some edge cases like what happens if the cabinet already exists are only implied by 'Add or update', but the overall context is solid.

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?

Despite 0% schema-description coverage, the description provides concrete parameter semantics: `credentials` is detailed with Ozan and WB examples, `name` is described as optional with fallback logic ('named after the real shop name... falls back to "main"'), and `i_understand_key_goes_to_chat` is clearly tied to the chat key risk. This compensates fully for the schema's lack of inline descriptions.

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

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

The description clearly states a verb and resource: 'Add or update a cabinet (a named set of API credentials), from chat.' It gives the object a concrete meaning and scopes the action to chat. It doesn't explicitly contrast with `diadoc_set_key` or other siblings, but the resource is clearly differentiated enough for an agent to guess when it applies.

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

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

The description explicitly mentions a safe alternative: 'The terminal-free safe alternative is the installer...' and implies this tool should be used only when the user accepts the key going into chat. It also requires (via parameter) an acknowledgment flag. It doesn't mention all siblings like `diadoc_use_cabinet` or `diadoc_remove_cabinet`, but the core when-to-use/when-not-to-use guidance is present.

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

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

The description adds behavioral details beyond the annotations: it states that reads run without confirmation, and it specifies the return envelope ('{"ok": true, "status", "data"} or the error envelope'). It also explains how path_values, query, and body are used. These are meaningful behavioral traits not present in the annotations or 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?

The description is well-structured: it opens with the core purpose, then the target API, then the read-only nature, then sibling routing, and finally a concise parameter breakdown. Every sentence adds value, and the most important info (read-only, usage) is front-loaded. 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?

Given the tool's generic nature (executing arbitrary read endpoints), the description covers all needed context: the API reference URL, the read-only guarantee, how to find operation_id, and the return format. The output schema exists, so the description doesn't need to list return fields. It is complete for an agent to call correctly.

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

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

The input schema has zero description coverage, but the description's 'Args' section explains each parameter: operation_id is the catalog id, path_values are for {placeholders} in the path, query is for query-string parameters, and body is a JSON request body for some read endpoints. This fully compensates for the schema's lack of semantic detail.

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

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

The description clearly states the action: 'Execute one READ endpoint from the catalog by operation_id.' It specifies a concrete verb, resource (READ endpoint), and the key identifier. It also differentiates from sibling tools by naming diadoc_write_method and diadoc_delete_method for non-read operations, so an agent can distinguish it immediately.

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

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

The description explicitly states when to use this tool: for read-only operations that run without confirmation. It also names alternatives for changing data (diadoc_write_method) and deleting (diadoc_delete_method), and directs the agent to diadoc_search_methods to find operation_id. This gives clear usage context and exclusions.

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

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

The description explicitly states that it does NOT reveal secret values and only reports which variables are set. This adds meaningful safety-relevant behavior beyond the readOnlyHint annotation and also describes the exact return shape, giving the agent full transparency about what the call will do.

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

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

The description is concise and structured with three short sentences. It front-loads the core purpose, adds an important behavioral safeguard, and then gives the exact JSON return shape, with no unnecessary content.

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 tool, the description is complete. It explains purpose, safety behavior, and return structure. The output schema and annotations further support this, leaving no important gap for an agent to invoke it correctly.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter semantics to clarify. The description focuses on the output and non-revealing behavior, which is appropriate in the absence of parameters.

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

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

The description clearly states a specific action: checking whether required credentials are present in the environment. It distinguishes itself from sibling tools like diadoc_set_key or diadoc_call_method by focusing on credential presence verification, making its purpose unmistakable.

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

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

The description clearly implies the tool is a read-only preflight check for credential presence. It does not explicitly name alternatives or state when not to use it, but its context is clear enough for an agent to understand when this check is appropriate.

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, so the baseline is lower. The description adds beyond that: it explains that both confirm_write=true and i_understand_this_modifies_data=true are mandatory, and that 'nothing is sent without both.' It also discloses the return envelope ({"ok": true, "status", "data"} or error). This is meaningful behavioral context beyond the annotations, with no contradiction.

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

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

The description is tightly written: a one-sentence purpose, the target API, the mandatory confirmation rule, and a clean bulleted list of arguments. There is no redundancy; every sentence serves a purpose, and the critical safety condition 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 generic destructive executor with 6 parameters, the description covers everything an agent needs: how to find the operation, what each parameter is for, the confirmation requirement, and the return format. It also provides the API URL and error envelope. The presence of an output schema reduces the need to describe returns, and the description adds the key operational constraints. Nothing essential 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 description coverage is 0%, so the description must compensate. It does: each parameter is given a brief but useful explanation—operation_id as an id from the catalog, path_values for placeholders, query as query-string parameters, body as JSON, and both confirm_write and i_understand_this_modifies_data explicitly marked as must-be-true. This provides meaning that the schema lacks, though it could add more detail about constructing the body/query, so a 4 is 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?

The description opens with 'Execute one DESTRUCTIVE endpoint' and immediately clarifies it 'deletes or irreversibly changes data.' This is a specific verb (execute) plus a resource (destructive endpoint) and a clear behavioral scope. It distinguishes itself from siblings like diadoc_call_method and diadoc_write_method by explicitly labeling the destructive nature and linking to the API catalog.

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

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

The description gives clear context: it is for destructive operations, requires confirmation flags, and references diadoc_search_methods to obtain operation IDs. It does not explicitly name non-destructive alternatives, but the destructive tag and the confirmation requirement strongly imply when it should be used. There are no exclusions stated, so it stops short of a perfect 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 mark this as destructive and non-read-only; the description adds useful context by requiring both confirmation flags and stating that the operation is DELETE-only. The return envelope ({"ok": true, "status", "data"} or error envelope) further clarifies expected behavior. No contradiction with the annotations is present.

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

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

The description is front-loaded with the dangerous delete warning and the required confirmation flags, then lists parameters compactly. It is slightly redundant because the args list repeats schema parameter names, but the added semantic hints, such as path format and host override behavior, justify the length.

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 powerful raw delete tool, the description covers the critical operational requirements: path format, method, confirmation flags, host override, and response envelope. Given that an output schema exists and annotations already signal destructive behavior, nothing essential is missing for an agent to invoke it safely.

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

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

With 0% schema description coverage, the description carries the parameter-documentation burden and does so reasonably well: path must begin with '/', method should be DELETE, host overrides the default, and both confirmation flags must be true. The query and body descriptions are thin ('query-string parameters', 'JSON request body'), which keeps this from a perfect score.

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

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

The opening phrase 'Delete data at ANY path, including paths not in the catalog' states a specific verb, resource, and scope. This clearly distinguishes the raw delete tool from catalog-scoped siblings like diadoc_delete_method, while the DELETE-only and confirmation-flag requirements reinforce its identity.

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

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

The description makes the intended use explicit: delete arbitrary paths, including ones outside the catalog. It also provides essential usage constraints by requiring confirm_write=true and i_understand_this_modifies_data=true. However, it does not explicitly state when to prefer a sibling tool or when not to use this one.

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?

The annotations already indicate readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It goes beyond any annotations by describing the automation of pagination and the hard cap (max_items) with a default of 10000 to protect context, which is additional useful behavioral detail. It also transparently states that the response is a JSON wrapper with truncation flag, though some of this is in 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?

The description is extremely efficient: a one-sentence summary up front followed by a compact list of parameter semantics. Every sentence adds value, and the formatting is scannable. It does not waste words on fluff or repeat schema information unnecessarily.

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?

Given the tool's complexity (handling multiple pagination styles) and the availability of an output schema, the description provides a complete picture: what it does, how to use it, parameters, and safety cap. It includes important defaults for max_items and limit)Skip to content. An agent has enough to invoke it correctly without ambiguity.

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

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

The schema has 0% description coverage, so the description carries a large burden. It explains operation_id (a read endpoint from the catalog), query/body/path_values (base parameters), items_path (override array path), limit (page size), and max_items (hard cap). This adds meaningful semantics beyond the bare parameter names. However, it could have elaborated on the JSON return structure in more detail, but the output schema exists to cover that.

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

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

The description clearly states that the tool auto-paginates a read endpoint and returns all rows, with a verb and resource that distinguishes it from other sibling tools like diadoc_get_raw which likely returns single responses. It also mentions the specific pagination styles, giving concrete detail. However, it does not explicitly contrast with siblings, so a slight deduction.

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

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

The description explains the tool's purpose well: use it to fetch all rows from read endpoints, while cursor fields are managed automatically. It does not explicitly state when NOT to use it or name alternatives like diadoc_call_method for pagination control, but the context of auto-pagination is clear. The guidance is implied but not exclusionary.

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

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

The annotations already declare readOnlyHint and openWorldHint, and the description reinforces this by restricting to safe verbs and explicitly naming the API target. It also adds meaningful behavioral details: host override semantics, JSON body usage, return envelope shape, and error envelope mention. No contradiction with annotations.

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

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

The description opens with the core purpose, includes a key reference link, then lists each argument with minimal but sufficient detail. It also names sibling tools where relevant. Every sentence adds value; there is no fluff or repetition of schema 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 raw 'get-by-path' tool with multiple optional parameters and an output schema, the description fully covers the operation's scope, argument semantics, constraints, and return shape. The inclusion of the return envelope and error envelope makes it self-sufficient even without an explicit output schema in the prompt.

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 input schema has 0% description coverage, so the description carries the full burden of documenting parameters. It explains the path format, the method default and allowed verbs, host override behavior, query-string parameters, and the rare use of body. This is exactly what an agent needs to call the tool correctly.

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

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

The description clearly states a specific action ('Read ANY endpoint by path') and the resource (endpoint path), and explicitly distinguishes itself from write/delete siblings. It also signals broad scope ('including ones missing from the catalog'), making the tool's role 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?

It explicitly states when to use this tool ('Read ANY endpoint by path'), restricts usage to safe verbs, and explicitly names the alternatives for mutations (diadoc_write_raw, diadoc_delete_raw). This gives an agent clear routing guidance without requiring separate tool discovery.

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 establishes that this is a safe read operation, and the description adds scoping information ('one section') plus the return format. There is no contradiction with annotations, but deeper behavior such as error handling, pagination, or auth requirements is not disclosed.

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

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

The description is compact and well-structured: one lead sentence, a one-line parameter explanation, and a return format. Every sentence earns its place, and the primary 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 read-only listing tool, the description includes the operation, parameter provenance, and return shape. It is mostly complete, though it could additionally mention behavior for an unknown section or any auth dependency shared across the sibling set.

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 schema description coverage at 0%, the description carries the burden for the section parameter. It explains that section is a section name, points to diadoc_list_sections for valid values, and provides 'statistics' as an example, which is more meaningful than the bare schema property.

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 object: 'List all endpoints in one section.' It clearly delimits the scope to a single section and references diadoc_list_sections, which helps distinguish it from the sibling that lists sections themselves.

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 statement makes the intended use case obvious, and the Args note tells the agent to obtain section names via diadoc_list_sections, giving a clear prerequisite. It does not explicitly enumerate when to choose this over other sibling tools, 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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral detail: the exact JSON shape returned, the presence of fields_needed, and the guarantee that 'Secret values are never returned.' This helps an agent understand expectations without calling the 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?

The description is two short sentences with no filler. The main action is front-loaded, and the return format plus security-relevant behavior are stated efficiently.

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 tool with an output schema available, this description is complete. It tells the agent what will be returned, notes that secrets are excluded, and gives enough context to invoke it safely.

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

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

There are zero parameters and the schema description coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 applies because the tool takes no arguments.

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: 'List configured cabinets for this marketplace'. It also clarifies that it reports which cabinet is active, which distinguishes it from sibling tools like diadoc_use_cabinet or diadoc_list_sections.

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

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

The description makes the use context clear: call this when you need to see the configured cabinets and the active one. It does not explicitly name alternatives or exclusion cases, so it stops short of full when-to-use versus when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=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 mark the tool as readOnlyHint=true, so safety is covered. The description adds behavioral details about what happens with no arguments versus with an entity argument, and frames the output as a map or method listing. This goes beyond the annotation without contradicting it.

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

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

Three sentences deliver the purpose, usage patterns, and when to use the tool. The phrasing is efficient and front-loaded with the core idea ('The big picture'), and every sentence 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 simple optional-parameter tool with an output schema and read-only annotations, the description covers what it does, how to invoke it, and when to reach for it. Nothing critical is missing for correct invocation.

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

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

The input schema only defines 'entity' as a string with a default, providing zero description coverage. The description fully compensates by explaining that omitting it shows the whole map and passing values like 'reviews' or 'stocks' lists methods for that entity. This gives the agent actionable meaning for the parameter.

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

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

The description clearly states what the tool does: it provides a map of business entities and their go-to methods. It also explains the two calling modes (no args for the whole map, entity argument for a single entity's methods), which distinguishes it from siblings like diadoc_search_methods or diadoc_describe_method.

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

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

The description explicitly says to use this tool before guessing and explains how to call it with or without the entity parameter. It does not name alternatives or state when not to use it, but the orientation purpose is clear enough that an agent can select it appropriately among siblings.

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, covering the mutating nature. The description adds the specific consequence that if the deleted cabinet was active, another becomes active, which is useful context beyond the annotations. No contradiction.

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 plus an Args line with zero waste. The action is front-loaded, and the behavioral note is concise. Every word 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 simple delete operation with one parameter, the description is adequate. It covers the core action and the important side effect. Output schema exists so return values need no explanation. Minor gaps like error handling or permissions are acceptable given the tool's simplicity and annotations.

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 clarify the parameter. It states 'name: the cabinet to remove', which gives clear meaning beyond the schema's bare 'Name' title. This is sufficient for a single string parameter, though it could mention format or 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?

The description clearly states the tool deletes a stored cabinet, which is a specific verb and resource. It distinguishes from siblings like add_cabinet, list_cabinets, and use_cabinet by focusing on deletion. The added note about active cabinets clarifies a specific side effect, making the purpose 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?

No explicit guidance on when to use this tool versus alternatives. It does not mention conditions for deletion, prerequisites, or when to prefer other cabinet-related tools. The only behavioral note is about active cabinet fallback, but it does not help the agent decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds behavioral context beyond annotations: it works in both Russian and English, returns results best-first, and enforces a result limit of 1-50. No contradiction with annotations exists.

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

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

The description is compact and front-loaded: one clear purpose sentence followed by a short Args block and a return statement. Every sentence carries useful information with no repetition of the schema or annotations.

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 two-parameter search tool with an output schema and readOnlyHint, the description is complete. It provides query examples, limit constraints, and return behavior, while the output schema covers the exact result shape. An agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, but the description fully compensates. It explains query as free text with concrete examples ('остатки', 'stocks', 'update price') and defines limit as 'max results (1-50)', adding practical meaning beyond the raw schema fields.

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

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

The description uses a specific verb and resource: 'Search the endpoint catalog by keyword.' It also mentions bilingual matching and returns a list of endpoints, which clearly distinguishes it from sibling tools like diadoc_describe_method, diadoc_call_method, or diadoc_get_raw.

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

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

The description implies usage: use this tool when you need to find endpoints by keyword. However, it never explicitly says when not to use it or names alternatives such as diadoc_describe_method or diadoc_list_sections, leaving some routing 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?

The annotations already mark the tool as not read-only and idempotent, so the description's main added value is in security and file-handling context. It warns that the key goes into the chat transcript, states the key is saved locally with chmod 600, never echoed back, and is validated against the marketplace. This goes meaningfully beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the core purpose. It uses a warning, a compact argument list, and a clear behavioral note about validation and saving. The minor repetition of the `i_understand_key_goes_to_chat` requirement in both the warning and the Args list is not harmful, and the unresolved `{fields}` placeholder is the only notable defect.

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 involving credentials, the description covers the safety aspects and cabinet selection, but the credentials shape remains underspecified. The output schema exists, so the caller can learn about the response, yet the required input fields inside the credentials object are still a notable unknown. Given the complexity and the sensitive nature, this is not fully complete.

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

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

The schema provides no descriptions (0% coverage), so the description must compensate. It does explain `cabinet` substantially and the requirement for `i_understand_key_goes_to_chat`, but the `credentials` parameter is only described as a dict with required fields, and the placeholder `{fields}` is not resolved. An agent still cannot tell exactly which fields are required in `credentials`, making this only partially successful.

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

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

The description immediately states that the tool changes or rotates the API key for a cabinet, with explicit use cases like an expired or leaked key. This clearly distinguishes it from siblings like diadoc_list_cabinets or diadoc_call_method, which either inspect or call other methods. The action and target resource are 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?

It explicitly says when to use the tool: when the old key has expired or leaked and must be changed from chat. It also names a safer alternative, the installer where the key never enters chat, and instructs to use a scoped key and rotate it in the seller cabinet if exposed. This gives the agent clear decision guidance against alternatives.

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

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

The description discloses the important stateful behavior: subsequent API calls use the switched cabinet's credentials. This adds meaningful context beyond the annotations (readOnlyHint=false, idempotentHint=true) and helps the agent understand the tool's side effects.

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

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

The description is two concise sentences with no filler. The main action is front-loaded, the consequence is stated immediately, and the parameter explanation is compact and useful.

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

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

The tool is simple, has one parameter, and an output schema is present, so the description does not need to detail return values. It covers the core behavior and parameter source well, though it could optionally mention what happens when an invalid name is provided.

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

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

The schema provides no description for the 'name' parameter, so the description compensates by explaining that name is 'the cabinet to activate' and pointing to diadoc_list_cabinets for valid values. This is sufficient for a single simple parameter.

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

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

The description states a specific verb and resource: 'Switch the active cabinet.' It clearly distinguishes this tool from siblings like diadoc_add_cabinet, diadoc_remove_cabinet, and diadoc_list_cabinets by focusing on activation rather than management or enumeration.

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

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

The description provides clear usage context: this tool changes which cabinet's credentials subsequent API calls use, and it references diadoc_list_cabinets as the source for valid names. It does not explicitly list exclusions or alternatives, but the intended workflow 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?

Annotations include readOnlyHint=false, destructiveHint=false, and openWorldHint=truenovel, but the description adds critical context: the confirm_write gate for safety and the irreversible nature of delete operations. It also mentions the return format, which is not in annotations. This goes beyond the structured 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?

The description is compact, with a brief intro, a link, then arg list and return envelope. It front-loads the key purpose. However, the Args section could be tightened and the target API link adds context that might be better placed elsewhere, but overall it's efficient.

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 details in annotations and schema coverage 0%, the description covers the essentials: purpose, confirm_write, return envelope. Yet it doesn't explain how to find operation_id beyond a sibling tool reference, nor does it detail error handling or special cases for write operations. Lacks some depth for complex writes.

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 explain parameters. It lists all parameters with brief roles (e.g., 'path_values for placeholders', 'query for query string', 'body for JSON'), but lacks deeper detail like typical structure or constraints for each. This is a slight improvement over 'no info' but still leaves the agent to infer specifics.

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

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

The description clearly states the tool executes one WRITE endpoint from a catalog, distinguishing it as a write operation. It names sibling tools for other operations (reads and deletes), but does not explicitly differentiate between the multiple write-related siblings like diadoc_write_raw, which could cause confusion.

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

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

The description explains the confirm_write requirement and mentions that irreversible operations are in diadoc_delete_method and reads in diadoc_call_method. However, it doesn't explicitly say when to use this tool over diadoc_write_raw, though the 'catalog' context implies it's for cataloged endpoints.

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

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

Annotations already signal readOnlyHint=false and openWorldHint=true; the description adds the HTTP method whitelist, the confirm_write guard, host defaulting behavior, and the return envelope/error envelope. It does not fully describe side effects or auth requirements beyond the target API link, but the annotation context lowers the burden.

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

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

The description is well-structured: purpose first, then API link, method restrictions, Args, and Returns. Minor redundancy exists between 'POST, PUT and PATCH only' and the method arg entry, but overall it is economical and scannable.

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 agent has enough information to invoke the tool correctly: all parameter semantics, required confirmation, and return shape are present. It could be more complete by explicitly relating it to sibling tools and addressing safety caveats of writing to arbitrary paths, but those are partially covered by annotations and the confirm_write requirement.

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%, yet the description documents every parameter: method values, path format, host override/default, query, JSON body, and the confirm_write guard. This fully compensates for the schema's lack of descriptions.

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

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

The opening sentence names a concrete verb ('Create or update') and a resource ('data at ANY path, including paths not in the catalog'), which clearly communicates the raw write scope. This also distinguishes it from catalog-based siblings like diadoc_write_method.

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

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

The description provides strong constraints (POST/PUT/PATCH only, confirm_write=true) and implies use for arbitrary/non-catalog paths, but it does not explicitly state when to prefer this over diadoc_write_method or call_method, nor when not to use it. The situational guidance is mostly left to inference.

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