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

The description goes far beyond annotations by disclosing the security-critical behavior: the key ends up in the chat transcript, the data is saved to ~/.marketplace-mcp/cabinets.json with chmod 600, and the key is never echoed. It also clarifies the upsert nature with 'Add or update,' aligning with the idempotentHint.

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-organized, with the purpose and critical warning front-loaded, followed by a structured Args section. Every sentence adds operational or safety value, and the file path/permissions detail is not padding.

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

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

Despite having an output schema, the description covers all operational context an agent needs: storage location, permissions, naming fallback, service-specific credential shapes, and the safety gate. Nothing essential 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?

Schema description coverage is 0%, but the description compensates by fully documenting all three parameters: credentials object with service-specific examples for Ozon and WB, optional name with fallback behavior, and the required i_understand_key_goes_to_chat boolean. This meaningfully exceeds what the bare schema provides.

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: 'Add or update a cabinet (a named set of API credentials), from chat.' It clearly names the operation, the resource type, and the interaction context, and it cannot be confused with sibling tools like ms_list_cabinets, ms_use_cabinet, or ms_remove_cabinet.

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 (from chat) and contrasts it with the terminal-free installer alternative where 'the key never enters chat.' It also documents the required consent flag, i_understand_key_goes_to_chat=true, leaving no ambiguity about 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 provide readOnlyHint: true and openWorldHint: true. The description adds behavioral details: it resolves names to refs, shows the exact body, and notes money is in kopecks. It confirms read-only nature. No contradictions. Lacks description of error scenarios or potential behavior on failure, but overall transparent.

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

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

The description is front-loaded with purpose and safety. Parameter documentation is thorough but somewhat verbose with nested lists. Could be slightly more concise, but structure is logical and easy to follow.

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 8 parameters, 2 required, 0% schema coverage, and an output schema present, the description is comprehensive. It explains all parameters, the return structure (including fields like resolved and summary), and even calls out specific behavior (auto-use organization, money in kopecks). No major gaps.

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

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

Schema coverage is 0%, so the description must compensate fully. It does: for each parameter it explains meaning (e.g., doc_type lists allowed values, agent defines counterparty role based on doc_type, organization auto-use, store requirement, positions format with fields and units, moment format). This adds essential context beyond the schema's type/title.

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 'PREVIEW any role document' and explains that it resolves names to refs and shows the exact body ms_create_document would send. It explicitly says 'READS only; no write', distinguishing it from sibling ms_create_document which creates. The verb and resource are specific and 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?

The description implies usage for previewing a document before creation via ms_create_document. It states 'READS only; no write' which guides when not to use (avoid if wanting to actually create). No explicit when-not-to-use or alternatives beyond the implied counterpart tool, but the context is clear enough.

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 that the tool performs reads only, resolving names to refs, and sends no write. This aligns with the readOnlyHint annotation. It also reveals the return structure (body, resolved, summary) and notes that money is already in kopecks, providing behavioral context beyond 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 is well-structured: a clear opening line, then a bulleted Args section. Every sentence adds value, no fluff. It is front-loaded with the core purpose and constraints, making it easy for an agent to quickly grasp what the tool does.

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?

Despite having an output schema (mentioned but not detailed), the description still summarizes the return envelope and expected fields. It covers all 7 parameters, the read-only behavior, and the relationship to creation. No important context is missing for a preview tool.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter in detail, including required nature (agent), optional auto-use (organization), structure of positions (list with fields and optional discount/vat), and moment format. This adds substantial meaning beyond the bare schema.

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

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

The description clearly states it is a PREVIEW tool that resolves names to refs and shows the exact body that ms_create_purchaseorder would send, explicitly distinguishing it from the creation sibling. It uses strong verbs like 'PREVIEW' and 'resolve names to refs', making the 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 provides explicit guidance: use before creating a purchase order to inspect the body/summary. It contrasts with ms_create_purchaseorder and explains that the tool performs reads only, not writes. It also mentions that organization can be auto-used, offering practical usage tips.

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 provide readOnlyHint=true, and the description reinforces that by stating 'Reads only: nothing here changes data'. It adds value beyond annotations by disclosing that it 'runs without confirmation' and by describing the success/error envelope ('Returns JSON: {"ok": true, "status", "data"} or the error envelope'). It does not cover rate limits or auth, but the core behavioral traits are well 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?

Every sentence earns its place: the purpose is front-loaded, safety implications are stated early, alternatives are named, arguments are summarized compactly, and the return shape is included. The structure is logical and scannable without 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 generic execution tool with four free-form parameters and an output schema present, the description is functionally complete. It provides the target API base URL, tells where to get operation_id, explains each parameter, names sibling tools for other operation types, and gives the response envelope. Nothing essential is missing 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?

Schema description coverage is 0%, so the description must compensate, and it does: each parameter gets a practical explanation (operation_id as catalog id, path_values for placeholders, query string parameters, and body for read endpoints that require one). This adds real meaning beyond the bare anyOf objects in the schema, though it stops short of giving syntax examples or formatting details.

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: 'Execute one READ endpoint from the catalog by operation_id', which is immediately clear. It also distinguishes itself from siblings by explicitly framing the tool as read-only and naming write/delete alternatives.

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 context is explicit: it is for reading data only and runs without confirmation, with clear redirection to ms_write_method for changes and ms_delete_method for deletions. The description also tells the agent where to find valid operation_ids (ms_search_methods), leaving little 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 description adds meaningful behavioral context beyond the readOnlyHint annotation: it states the tool never reveals secret values and only reports which variables are set. It also specifies the exact JSON return shape (ready, missing, required), making the tool's behavior predictable and safe.

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

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

Three short sentences each carry distinct value: the tool's purpose, a critical security guarantee, and the return format. The text is front-loaded with the main action and contains 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-argument, read-only check with an output schema, the description fully equips an agent to select and invoke the tool correctly. It covers what the tool does, what it does not do, and what the response looks like.

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 accepts zero parameters, so the input schema fully defines the call surface; the rubric baseline for zero-parameter tools is 4. The description adds no parameter-level details because none 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?

The description uses a specific verb ('check') and a clear resource ('credentials present in the environment'), and it clarifies that the tool only reports presence, not secret values. It stands apart from siblings like ms_set_key by emphasizing it does not reveal secrets, though it does not explicitly name alternatives.

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 intended use as a credential preflight check is implied by the description, and the explicit statement that it does not reveal secrets helps rule out using it as a credential fetcher. However, there is no explicit guidance about when to run it before other tools or when to prefer an alternative.

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?

Describes behavior beyond annotations: draft creation, required environment variable, guard/validation error returns. Annotations indicate write but not destructive, which matches.

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

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

Efficient, front-loaded: purpose, requirements, parameter list, return format. Every sentence adds value.

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?

Covers core behavior, all parameters, return format, and error cases. With output schema present, return description is sufficient.

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 description lists all parameters, provides enum values for doc_type, and references ms_build_document for details. Adds meaning beyond bare 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?

Clearly states the action: 'Create ANY role document as a DRAFT' with specific verb and resource. Distinguishes from ms_post_document (posting) and notes key constraints like applicable=false.

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

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

Explicitly notes that posting is a separate step (ms_post_document) and specifies prerequisites (confirm_write, MOYSKLAD_ALLOW_WRITE). Does not explicitly list when to use or not use, but context is clear.

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

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

The description discloses that the tool is a WRITE operation requiring confirm_write=true, and explains the guard/gate error behavior. Annotations already set readOnlyHint=false and destructiveHint=false, but the description adds specific behavioral details beyond annotations, such as the draft nature and the environment variable.

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 well-structured: it starts with the tool's purpose, then adds behavioral and usage notes, and finishes with return value info. Every sentence adds value, and there is no redundancy or waffle.

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 (8 parameters, 1 required, output schema exists, annotations provided), the description covers behavioral and usage context well but fails to explain parameter meanings. This gap is significant for agents that cannot look up ms_build_purchaseorder's arguments. The presence of an output schema mitigates return value explanation, but parameter semantics remain incomplete.

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 must compensate. However, it only says 'Args: same as ms_build_purchaseorder, plus confirm_write', without explaining each parameter's meaning or purpose. This is insufficient for an agent to understand parameter semantics without consulting another tool's definition.

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 'Create a purchase order as a DRAFT (applicable=false)', specifying the exact verb and resource. It distinguishes from siblings like ms_post_document by noting that posting is separate, and from ms_build_purchaseorder by mentioning it adds confirm_write.

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 when to use this tool (to create a draft purchase order) and notes that posting is done via ms_post_document. It also warns about the confirm_write requirement and the MOYSKLAD_ALLOW_WRITE=1 environment variable. However, it does not explicitly state when NOT to use it, though the context implies it.

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 context beyond annotations: it specifies the need for two confirmations and describes the return format (success response or error). Annotations already mark destructiveHint=true, so the description enhances understanding without 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 concise (two main sentences plus a structured Args/Returns block). It front-loads the purpose and warning, then lists parameters and output. Every part is useful and no unnecessary text.

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 annotations marking destructive behavior and the description covering purpose, parameters, and response, the tool is well-defined. The only minor gap is not explicitly naming the confirmation parameters, but the description's warning suffices. The presence of an output schema reduces the need for return value details.

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 lists the two required parameters (doc_type, doc_id) and provides an explicit enumeration of valid doc_type values. It also implies the two boolean confirmation parameters by stating 'requires both confirmations,' which adds meaning beyond the schema's default values.

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 ('DELETE a document'), the resource (document), and provides an example ('remove a test draft'). It distinguishes from sibling tools like ms_create_document or ms_get_documents by emphasizing deletion and destructive nature.

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 mentions the tool is destructive and requires confirmations, but it does not explicitly state when to use it over alternatives or provide when-not scenarios. The context implies deletion tasks, but lacks explicit 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 mark destructiveHint=true and readOnlyHint=false, but the description adds crucial behavioral detail: both confirm_write and i_understand_this_modifies_data must be true, and 'nothing is sent without both.' This goes beyond the structured annotations and gives the agent a clear safety gate for an irreversible action. It also discloses the return envelope shape.

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 with a front-loaded destructive warning, a target API link, required-flag emphasis, and a clear args list. There is minor redundancy around the confirmation flags (stated twice), and the return example has a small formatting quirk, but overall it is appropriately sized 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?

For a complex destructive tool with 6 parameters and 0% schema coverage, the description covers the essential invocation details: where to get operation_id, how path_values work, confirmation requirements, and the return envelope. It does not explain the error envelope structure or fully elaborate query/body semantics, but the output schema and API link cover some of that ground.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so for operation_id by pointing to the catalog, defines path_values as placeholder substitution, labels query and body accurately, and explicitly marks both confirmation booleans as required. It could add more detail about query/body formatting, but it compensates well for the missing schema 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 opens with a specific verb and resource: 'Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data.' This clearly establishes the tool's destructive nature and distinguishes it from sibling tools like ms_call_method and ms_delete_raw by framing it as a catalog-driven endpoint operation rather than a raw call.

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: use this for a destructive catalog endpoint, and it directs the agent to ms_search_methods for obtaining operation_id. It does not explicitly list exclusions or alternative tools for non-destructive operations, so it falls short of a 5, but the usage context is unambiguous.

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, but the description goes beyond by stating the confirmation requirements (confirm_write and i_understand_this_modifies_data must be true) and the return JSON structure. It also notes the possibility of deleting non-catalog paths, adding operational context. 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 is well-structured with a clear opening, protocol link, and bullet-pointed arguments. It is a bit long due to the enumerated args, but the information is necessary and front-loaded. The API link is extra but potentially useful. Overall, it 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 destructive raw delete tool, it covers the essentials: what it does, required safeguards, path format, and return envelope. It does not elaborate on error handling beyond 'error envelope' or side effects on related data, but the confirmation flags mitigate risk. Given the output schema exists, the description is sufficiently complete for an agent to invoke 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%, so the description must shoulder the burden. It lists all 7 parameters with brief meanings: path format, method default, host override, query, body, and the two confirmation booleans with required values. It doesn't give detailed structure for query/body, but those are open-ended, and it does compensate for the lack of schema descriptions. Slight improvement would be explaining that query/body are optional and typically used for filtering or payloads.

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: 'Delete data at ANY path, including paths not in the catalog.' It clearly distinguishes itself from sibling tools like ms_delete_method and ms_delete_document by targeting arbitrary raw paths. The purpose is unambiguous and action-oriented.

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 specifies the method (DELETE only) and the required confirmation flags, and implies it is for paths outside the catalog. However, it does not explicitly contrast with sibling deletion tools (e.g., 'use ms_delete_method for structured deletes'). This is a minor gap, but the context is clear enough for an agent to select it when dealing with raw paths.

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 indicate readOnlyHint=true, and the description adds that the tool returns a catalog record, reinforcing its read-only nature. It also lists the fields returned, providing transparency about the output. No contradictions.

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 a single concise sentence that efficiently enumerates the output fields without any redundancy. Every word adds value.

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 low complexity (one parameter, defined output) and the presence of an output schema (not shown), the description adequately covers the tool's purpose. It lists the returned fields, though it could mention that the operation_id must correspond to a valid endpoint.

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 sole required parameter operation_id has no schema description (coverage 0%), and the description does not elaborate on its meaning or how to obtain it. The agent is left guessing what value to provide, which is a significant 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?

The description clearly states it returns a full catalog record for one endpoint, listing specific fields (method, host, path, scope, safety level, pagination style, rate limit, params, doc URL). This sufficiently distinguishes it from siblings like ms_search_methods (which likely searches) and ms_call_method (which executes).

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 for retrieving details of a specific endpoint but provides no explicit guidance on when to use this tool versus alternatives like ms_search_methods. It does not mention exclusions or 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 readOnly and openWorld, and the description adds substantial behavior: it manages cursor fields, auto-derives the array path, enforces a max_items cap, and returns a truncated flag. This exceeds the structured data 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?

The summary line is front-loaded, the Args section is a compact list, and the return shape is given in one line. There is no filler or repetition; 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 7-parameter tool with 0% schema descriptions and no destructive behavior, the description covers the operation, all parameters, pagination behavior, and the exact return envelope. An output schema exists, so the absence of deeper return-field documentation is acceptable.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does: operation_id is identified as 'a read endpoint from the catalog', query/body/path_values are called base parameters, items_path is an override, limit sets page size, and max_items caps the result. Every parameter receives semantic context beyond name and type.

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 line names the operation and resource precisely: 'Auto-paginate a read endpoint and return every row in one response.' It is clear about the tool's function, but it does not explicitly name a sibling alternative such as ms_call_method or ms_get_raw, so it misses the differentiator needed for 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?

The description clearly establishes the intended use case—fetching all rows from a read endpoint without manual pagination—and lists the pagination styles it supports. It does not explicitly state when not to use it or which sibling tool to choose instead, but the context is strong enough for an agent to route correctly in most cases.

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 indicate readOnlyHint and openWorldHint, so the description adds value by detailing the unit (kopecks) and the rubles conversion parameter. It also describes the return format. No contradictions 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 is concise and front-loaded, clearly stating the purpose first. Each sentence earns its place, providing parameter details and return format without unnecessary words. Slight pseudo-code for filter is acceptable.

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 presence of output schema and annotations, the description covers key aspects: what the tool does, how to paginate and filter, and unit conversion. It lacks error handling details but is sufficient for a read-only retrieval tool.

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

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

With 0% schema description coverage, the description effectively explains all four parameters: limit/offset for pagination, filter with MoySklad syntax example, and rubles for kopeck-to-ruble conversion. This adds significant meaning beyond the raw schema.

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

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

The description clearly states it retrieves counterparties (customers and suppliers) with balance fields in kopecks, and the name reinforces this. It is specific and unambiguous, distinguishing it from other sibling tools like ms_get_documents or ms_get_products.

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 lacks guidance on when to use this tool over alternatives. It only explains how to use parameters (pagination, filter, rubles) but does not specify scenarios, prerequisites, or exclusions. No comparison with sibling tools is provided.

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=true. The description adds valuable context: the sum field is in kopecks, the rubles conversion parameter, and the filter syntax example. No contradictions.

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 front-loaded with the core purpose. Every sentence adds value, including the docstring-style argument list. No waste.

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 has 5 parameters and an output schema, the description covers all inputs, output format, and behavioral details (filter example, rubles default). The annotations complement it well. An agent has sufficient information to use the tool 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: doc_type lists valid values, limit/offset for pagination, filter gives a concrete example, and rubles explains conversion. The return JSON structure is also described.

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 'List a role document by type', providing a specific verb and resource. It distinguishes from sibling tools like ms_create_document or ms_delete_document which handle mutations. The mention of 'Document total in sum (kopecks)' adds precision.

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 arguments, pagination, and filtering but does not explicitly state when to use this tool versus alternatives. Given many document- and listing-related siblings, explicit guidance would help. The information is still useful but not comparative.

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 annotations (readOnlyHint, openWorldHint), the description informs about the return format, the optional rubles conversion, and that it returns a snapshot of balances. No contradictions 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?

Concise, front-loaded statement of purpose, followed by usage hint and parameter explanation. Every sentence adds value, no waste.

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 tool with a single parameter, the description comprehensively covers purpose, usage, behavior, and return format. Output schema and annotations supplement nicely.

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 sole parameter 'rubles' is fully described with its purpose and default value, compensating for the 0% schema description coverage.

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?

Clearly states it returns cash balances by account/cashbox in kopecks, and distinguishes itself from the cashflow-over-time tool via a specific function call reference.

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

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

Explicitly directs users to an alternative tool (ms_get_report_money_plotseries) for cashflow over time, providing clear context for when to use this tool versus another.

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 reveals that the 'sum' field is in kopecks and that the rubles parameter converts to rubles. It also returns a JSON structure with meta and rows, adding 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?

The description is well-structured with bullet points for arguments and return format. It is concise, but could be slightly more streamlined by integrating the sum explanation more naturally.

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 description covers key aspects: purpose, parameter details, filter syntax, money conversion, and return structure. The existence of an output schema reduces the need to detail return fields. No mention of errors or limits, but sufficient for typical use.

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 enriches all 4 parameters with details: limit max 1000, offset pagination, filter with example, and rubles conversion purpose.

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 'List customer orders' with a specific verb and resource, and it distinguishes from sibling tools like ms_get_documents and ms_get_counterparties by focusing on orders.

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 guidance on when to use this tool versus alternatives (e.g., ms_get_documents for all documents). The description only provides operational details, not comparative usage context.

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?

Description adds value beyond annotations by explaining the return format (JSON with ok/data), the kopecks-to-rubles conversion, and the limit maximum of 1000. It aligns with the readOnlyHint annotation without 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 concise (8 lines), front-loads the purpose, and then explains parameters efficiently. Every sentence adds necessary information without 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?

Given the presence of an output schema and annotations, the description is largely complete. It covers parameters and return structure. Minor missing detail about error handling for invalid filters, but overall sufficient.

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?

All four parameters are explained in detail beyond the schema: limit max 1000, offset for pagination, filter with MoySklad expression example, and rubles conversion with default. The schema has 0% coverage, so description fully compensates.

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?

Description clearly states the tool lists products/services/bundles with prices and stock. It uses a specific verb ('List') and resource ('products/services/bundles'), distinguishing it from sibling tools like ms_get_stock or ms_get_orders.

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 guidance on when to use this tool versus alternatives. The description does not mention conditions, prerequisites, or situations where other tools might be more 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 readOnlyHint=true, so the read-only behavior is clear. The description adds value by disclosing pagination (limit/offset), period bounds (moment_from/moment_to), and the rubles conversion toggle, which are behavioral aspects beyond the annotation.

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 well-structured: a one-sentence purpose statement, followed by a succinct list of arguments with explanations, and the return format. Every sentence adds value without unnecessary detail.

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 that an output schema exists, the description does not need to detail return values. It covers all essential aspects: purpose, all 5 parameters with clear explanations, and the return structure. The tool is non-destructive (readOnlyHint), and no prerequisites are missing for typical use.

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 so thoroughly by explaining each parameter's purpose: moment_from/moment_to as date-time strings in a specific format, limit/offset for pagination, and rubles for converting kopecks to rubles. This adds necessary meaning beyond the schema's field names and types.

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's purpose: 'Profitability by product (sale, cost, profit, margin).' It distinguishes itself from sibling tools like ms_get_money and ms_get_turnover by focusing on profitability breakdown per product.

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 guidance is provided on when to use this tool versus related tools such as ms_get_turnover or ms_get_money. The description only explains parameters and return format, leaving the agent to infer usage context.

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=true. The description adds meaningful context beyond these: the specific safe-verb restriction, the host-override default behavior, the return envelope shape ('{"ok": true, "status", "data"}'), and the note that some read APIs accept a body. The error envelope is mentioned but not detailed, keeping this just short of a 5.

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

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

The description is front-loaded with the core purpose, followed by the API reference link, verb constraints, sibling routing, a clean Args block, and the return format. Every sentence earns its place; 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 raw passthrough tool with 5 parameters and 0% schema coverage, the description covers purpose, target API, verb constraints, parameter semantics, defaults, examples, alternatives, and return format. An output schema exists, so return values need not be elaborated further. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden of parameter documentation. It documents all 5 parameters with actionable detail: path format with a concrete example prefix, method default, host override semantics, query-string purpose, and body usage note. 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 description states a specific verb and scope: 'Read ANY endpoint by path, including ones missing from the catalog.' It clearly identifies the resource (raw API endpoints by path) and is immediately distinguishable from sibling tools because it names the write and delete alternatives it is not.

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

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

Explicit routing guidance is provided: 'Safe verbs only (GET, HEAD, OPTIONS). To change data use ms_write_raw, to delete use ms_delete_raw.' This tells the agent exactly when to use this tool versus its siblings, leaving nothing to inference.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, and the description is consistent with both. It adds behavioral value by stating that it returns 'all endpoints' and by documenting the exact return item shape ({operation_id, method, path, safety, summary}). It doesn't cover error behavior for unknown sections, but that's a minor gap for a simple read-only listing.

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: a one-sentence purpose, an Args line, and a Returns line. There is no redundant prose, and the example is directly useful rather than decorative.

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

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

For a one-parameter, read-only listing tool with an output schema available, the description covers purpose, parameter derivation, and return shape. An agent has everything needed to select and invoke the tool correctly, and the sibling reference handles the only source of 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 input schema has no description for the 'section' parameter (0% schema coverage), so the description carries the full burden. It does this well: it defines 'section' as a section name, points to ms_list_sections as the source of valid values, and gives a concrete example ('statistics'). This fully compensates for the bare schema.

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

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

The description states a specific verb ('List'), resource ('endpoints'), and scope ('one section'), which clearly distinguishes this from sibling tools like ms_list_sections (which lists sections) and ms_search_methods (which searches). The example and reference to ms_list_sections reinforce exactly what the tool operates on.

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 primary use case clear: call this when you need all endpoints within a named section. It also gives practical guidance by pointing to ms_list_sections for valid section names and providing a concrete example. It doesn't explicitly discuss when to prefer ms_search_methods, but the context is clear and no exclusions are needed.

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 (readOnlyHint, openWorldHint) indicate safe read-only behavior. The description adds value by explaining the fast-report nature, default stock_type behavior, include_zero effect, and return format (JSON with data array). It does not contradict annotations and provides useful behavioral context beyond the metadata.

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 concise: 5 lines covering purpose, parameters, and return format. No redundant words; every sentence earns its place. Front-loaded with key action and resource.

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 an output schema exists, the description adequately explains the return structure ('Returns JSON: {"ok": true, "data": [ {assortmentId, <stock_type>}, ... ]}'). Both parameters are documented, and edge cases (include_zero, no money) are addressed. No gaps remain for a simple stock snapshot tool.

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

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

Schema coverage is 0%, but the description explains both parameters: stock_type (lists possible values: quantity, freeStock, reserve, inTransit, stock, with default) and include_zero (boolean effect). This adds meaning beyond the schema, which only has types and defaults.

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 'Current stock snapshot, grouped by product' with specific verb and resource. It distinguishes from siblings like ms_get_products (product catalog) and ms_get_money (financial reports) by focusing on stock levels and noting 'No money in this report.' The path and grouping add specificity.

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 use for stock snapshots but does not explicitly state when to use this tool vs alternatives like ms_get_products or ms_get_stores. No exclusions or alternative suggestions are provided, leaving the agent to infer from the resource name.

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 indicate readOnlyHint=true and openWorldHint=true. The description adds value by specifying the JSON response structure (including fields like meta, rows, name, id) and noting the absence of money fields, providing concrete behavioral context beyond 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 is extremely short (two lines) and front-loaded with purpose, but it omits critical information about parameters. It is concise but under-specifies, losing points for missing essential details.

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 simplicity (read-only list with two parameters) and existing annotations, the description partially covers the output format. However, it does not explain pagination (limit/offset) or the list nature explicitly, and lacks guidance on usage context among 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?

Schema coverage is 0%, meaning the JSON schema provides no descriptions for limit and offset. The description does not mention these parameters at all, failing to compensate for the lack of schema documentation. This leaves the agent with no meaning for the 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 the tool fetches warehouses/stores, calling it a 'small dictionary' and specifying 'no money fields'. This distinguishes it from siblings like ms_get_money, ms_get_products, etc.

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 guidance on when to use this tool versus alternatives. Does not mention scenarios where it should or should not be used, nor does it reference any prerequisites or 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?

Annotations already mark it as read-only. The description adds valuable behavioral context: return format (JSON with meta/rows), pagination support, and the kopecks-to-rubles conversion. This goes beyond annotations and helps the agent understand behavior.

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 structured with clear sections for arguments and return value. While it contains many details, every sentence contributes useful information. It is not overly verbose but could be slightly tighter.

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 has an output schema, the description's mention of the return format is sufficient. It covers the key aspects: report period, pagination, and unit conversion. It is complete enough for an agent to understand usage without significant 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?

With 0% schema description coverage, the description compensates well by explaining all 5 parameters: moment_from/moment_to as date strings, limit/offset for pagination, and rubles for conversion. It adds meaning beyond the schema's default values.

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 it retrieves turnover by product with opening/income/outcome/closing quantities and money. The verb 'get' and resource 'turnover' are specific, and the naming distinguishes it from sibling tools like ms_get_stock or ms_get_profit.

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 no guidance on when to use this tool versus alternatives like ms_get_profit or ms_get_stock. It only describes what the tool does without contextual comparison.

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 details what the tool returns: ordered steps with operation IDs, interpretation guidance, and common mistakes. This adds significant context beyond the readOnlyHint annotation, which only indicates safety.

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 (4 lines), front-loaded with the purpose, and uses a clear Args section for parameter documentation. No superfluous 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 simple one-parameter read-only tool with an output schema, the description fully explains the return content and references the sibling list tool for parameter qualification. It is 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?

With 0% schema coverage for the 'name' parameter, the description compensates by explaining it is a 'workflow name (see {svc}_list_workflows)'. This provides meaningful guidance on how to supply 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 the tool returns 'the full plan for one workflow: ordered steps, interpretation guidance, and common mistakes.' It distinguishes from the sibling ms_list_workflows by focusing on a single workflow's detailed plan.

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 implicitly advises using ms_list_workflows first to obtain valid workflow names (see the 'Args' reference). However, it does not explicitly state when not to use this tool or compare it to 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?

Annotations already mark this as read-only, and the description adds useful behavioral context: it returns JSON with active/cabinets/fields_needed and guarantees that secret values are never returned. This reassures the agent about side effects and data safety beyond the basic read-only flag.

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 no filler; the main action is front-loaded and the return-structure detail is immediately useful. Every sentence adds information about behavior or output.

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, the description plus readOnlyHint and output schema cover everything an agent needs. It states the purpose, the output fields, and the confidentiality guarantee, with no missing prerequisites or side-effect considerations.

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, and context signals indicate 100% schema description coverage, so there is no parameter gap to compensate. The description's mention of the return shape helps the agent understand what the no-argument call yields.

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 the specific verb 'List' with the resource 'configured cabinets' and explicitly says 'for this marketplace and which one is active.' This clearly distinguishes it from sibling tools like ms_use_cabinet or ms_add_cabinet, which target different operations on cabinets.

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 states what the tool does but does not explicitly say when to choose it over alternatives or when not to use it. The intended use case is implied by the verb, and siblings like ms_use_cabinet suggest complementary actions, but there is no explicit routing guidance.

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

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

Annotations already indicate readOnlyHint=true, making the safety profile clear. The description adds behavioral context by specifying that the tool returns a list of sections with endpoint counts, which is beyond what annotations provide. No contradictions.

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 a single, concise sentence that immediately states the purpose. No redundant or verbose phrasing.

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

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

For a simple, parameterless tool with an output schema, the description sufficiently communicates what the tool does and what it returns. It is complete given the low complexity.

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

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

There are no parameters, and schema description coverage is 100%. The description does not need to explain parameters and instead focuses on the output, which is appropriate. Baseline is 4 for zero 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 specifies the verb 'List', the resource 'API sections', and the additional information provided ('how many catalog endpoints each contains'). It distinguishes from siblings like ms_get_section (which likely returns details for one section) and other list tools.

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 guidance on when to use this tool versus alternatives such as ms_get_section or ms_list_cabinets. The description does not mention prerequisites, limitations, or scenarios where other tools are preferable.

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 description doesn't need to repeat. It adds value by describing the JSON return format (name, category, when_to_use) and linking to the next tool.

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

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

Two concise sentences, front-loaded with purpose, no wasted words.

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 simplicity (zero params, read-only) and existence of output schema, the description fully covers what an agent needs: purpose, usage, and next step.

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?

No parameters in schema, so no parameter documentation needed. Baseline 4 for 0 params. Description is adequate.

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?

Clearly states the tool lists ready-made analytical workflows (recipes) for the marketplace, distinguishing itself from the sibling ms_get_workflow which retrieves full details.

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

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

Explicitly tells when to use this tool (to list workflows) and when to use an alternative (use {svc}_get_workflow for full step-by-step plan).

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 the description adds behavioral detail: calling with no args shows the entire map, passing an entity lists all methods for that entity. This goes beyond annotations and clarifies the 'you are here' metaphor, helping the agent understand what output to expect without overcommitting.

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

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

Two sentences, front-loaded with purpose and usage. The informal metaphors ('you are here', 'big picture') are engaging but slightly less precise than formal wording. Still, every sentence earns its place and the structure is 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?

The description covers both invocation modes (no args, with entity) and its role as an orientation tool. With an output schema present, it doesn't need to explain return format. It could benefit from listing all valid entities, but the map itself will provide that, so it's complete enough for the agent to call it correctly.

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

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

Schema coverage is 0% (the one parameter 'entity' has no description), so the description carries full responsibility. It explains that entity is a string representing a business entity (e.g., 'reviews', 'stocks', 'prices', 'orders') and that passing it filters the map to that entity. This fully compensates for the gap and gives concrete examples.

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 it is a map of business entities and their methods, with a specific verb ('call') and resource ('the whole map'). It explicitly distinguishes itself from sibling tools by positioning itself as the orientation tool before guessing, which differentiates it from search/describe tools.

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

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

It gives clear context on when to use it ('before guessing') and how to use it (no args for whole map, entity for specific). It doesn't explicitly mention alternative tools or when not to use, but the 'before guessing' instruction implies it's the first step, which is sufficient guidance for this orientation 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?

Describes the return format on success ('ok, status, data') and error ('canonical error envelope'). Annotations provide readOnlyHint and openWorldHint, and description adds behavioral details without 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 sentences: first states purpose and operation, second explains response and usage. Front-loaded, no wasted words.

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 zero parameters and an output schema, the description sufficiently covers the tool's behavior. It explains the purpose, the response envelope, and usage context. Sibling tool differentiation is implicit via the specific endpoint mentioned.

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?

No parameters in schema, so baseline is 4. Description adds context about the underlying GET request (assortment?limit=1), providing useful implementation detail beyond 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?

Explicitly states 'Live connectivity + auth check' and mentions the specific API call 'GET assortment?limit=1'. Title from annotations further confirms 'MoySklad live auth check'. Distinguishes from sibling tools like ms_check_auth by specifying the endpoint.

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?

Directly advises 'Use this on the cabinet to confirm the token before anything else', giving clear when-to-use context. Does not explicitly exclude alternatives, but the instruction implies it is the first step.

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 indicate destructiveHint=true, and the description reinforces this by explaining the financial and stock movements. It also details the safety guard parameters, ensuring the agent understands the risk.

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, starting with the core action and effects, then destructiveness, then parameters, then return value. Every sentence adds value without 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?

Given the destructive nature and presence of an output schema, the description covers what the tool does, required inputs, safety parameters, and the possible return (updated document or error). It is comprehensive for an agent to use 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?

With 0% schema description coverage, the description adds crucial meaning: it lists valid doc_type values, explains doc_id as the ID from creation, and clarifies that confirm_write and i_understand_this_modifies_data are confirmation flags. It could provide more detail on defaults, but is sufficient.

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 posts a document by setting applicable=true, which moves stock and money. It explicitly separates this action from creation, distinguishing it from sibling tools like ms_create_document.

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 specifies the requirement for confirm_write=true and i_understand_this_modifies_data=true, emphasizing the destructive nature. It implies use after creation but does not explicitly state when not to use or list 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?

Annotations already signal destructiveHint=true, and the description adds a valuable behavioral trait: 'If it was active, another becomes active.' It does not fully specify how the next active cabinet is chosen, but it goes beyond what the structured annotations provide.

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 compact sentences plus one argument line. Every sentence contributes: the action, the side effect, and the parameter meaning. There is no fluff.

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

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

For a one-parameter destructive tool with an output schema, this is nearly complete. It states the effect and the side effect; a small gap is not explaining how to identify a cabinet or what the response contains, but the output schema covers returns.

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 the parameter. It does: 'name: the cabinet to remove.' This adds meaning beyond the bare schema field by tying the string to the resource being deleted.

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: 'Delete a stored cabinet.' It clearly identifies the operation and is not a tautology of the tool name, and the active-cabinet side effect helps distinguish removal from other cabinet actions.

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 use case is implied: if you need to remove a stored cabinet, call this tool. However, it does not explicitly compare against sibling deletion tools such as ms_delete_method or ms_delete_document, nor does it state when not to use it.

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 useful behavioral context: search works in Russian and English, returns a JSON list, and results are ordered best first. 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 is compact and efficient: one clear purpose sentence, two parameter lines, and a return-type line. Every sentence adds value and the 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 search tool with a simple parameter set and an output schema, the description fully covers invocation requirements: search terms, result limit, supported languages, return format, and ordering. Nothing needed to call the tool correctly is missing.

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

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

The input schema has 0% property description coverage, so the description carries full responsibility for explaining parameters. It explains 'query' with concrete examples and 'limit' with an explicit range (1-50), providing meaning well beyond the bare 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?

Description states a specific verb and resource: 'Search the endpoint catalog by keyword.' It clearly identifies what the tool does and distinguishes it from siblings like ms_describe_method or ms_call_method, which target individual endpoints rather than discovering 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?

The description implicitly defines when to use the tool: when you need to find endpoints by keyword. It does not explicitly name alternatives or state when not to use it, but the context among siblings makes the appropriate use 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?

Beyond the annotations, the description discloses a critical safety behavior: the key enters the chat transcript and requires an explicit acknowledgment flag. It also states the key is validated against the marketplace, stored locally with chmod 600 permissions, and never echoed back. No annotation contradiction 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 dense but every sentence earns its place: the warning, the alternative, the parameter semantics, and the success behavior. The Args section is clearly organized and the safety warning 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?

The description is strong on purpose, safety, and postconditions, and there is an output schema available. However, the unexplained '{fields}' placeholder for the sole required parameter leaves a material gap: an agent cannot reliably construct the credentials dict without additional information.

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 needed to explain the parameters itself. It does clarify cabinet defaulting and the i_understand_key_goes_to_chat requirement, but the required credentials parameter is described only as 'dict with the required fields ({fields})' — an unresolved placeholder that gives the agent no concrete fields or shape to use.

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: 'Change / rotate the API key from chat', with concrete trigger examples ('expired or leaked'). It also distinguishes itself from the installer-based alternative, making it easy to tell this tool apart from the surrounding cabinet/auth tools.

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 chat-based path vs. the installer alternative, and warns that the key will appear in the transcript unless i_understand_key_goes_to_chat=true. It even gives follow-up guidance about using a scoped key and rotating it in the seller cabinet if exposed.

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 and idempotentHint=true. The description adds meaningful context by clarifying that it changes the active cabinet and that this affects subsequent calls, which the annotations don't convey. There is no contradiction with the 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 is concise and well-structured. The main action is front-loaded in the first sentence, the effect is stated in the second, and the parameter is explained in a single line. There is 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 tool with one required parameter and an output schema, the description covers the essential aspects: purpose, effect, and parameter semantics. It also points to ms_list_cabinets for valid values. Minor gaps like error handling are not critical for this simple operation, so the description is sufficiently 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 has no description for the 'name' parameter (0% coverage). The description compensates by explaining it is 'the cabinet to activate' and referencing ms_list_cabinets for valid names. This adds significant meaning beyond the bare property title 'Name' in the schema.

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

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

The description states a clear verb and resource: 'Switch the active cabinet.' It also explains the effect ('Subsequent API calls use its credentials'), which makes it distinct from tools like ms_list_cabinets or ms_add_cabinet. 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?

The description implies when to use it: before making other API calls that depend on the active cabinet's credentials. It even directs the user to ms_list_cabinets for valid names, providing helpful context. However, it doesn't explicitly state exclusions or name alternatives like ms_add_cabinet, though that's not critical for this simple switch operation.

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 and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context: the confirm_write gate ('nothing is sent without it'), the target API URL, and the return envelope ('Returns JSON: {"ok": true, "status", "data"} or the error envelope'). It doesn't detail side effects or reversibility, but the sibling routing covers the destructive case. This exceeds the baseline for annotation-covered tools.

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: the core purpose appears in the first sentence, the critical confirm_write requirement in the second, and sibling routing in the third. The Args list is terse and each line earns its place. No filler or repetition of schema details.

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 5-parameter tool with no schema descriptions, the description covers the essential context: target API, safety gate, sibling routing, parameter semantics, and return format. The output schema exists, so return values need no further explanation. Minor gaps: it doesn't mention authentication requirements or error-handling specifics, but the error envelope is noted and the target API link provides a reference. This is nearly complete for an agent to invoke the tool 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%, so the description must compensate. It explains each parameter's role: operation_id is 'id from the catalog (see ms_search_methods)', path_values are 'values for {placeholders} in the path', query is 'query-string parameters', body is 'JSON request body', and confirm_write 'must be true'. This adds meaning beyond the bare schema titles and gives the agent enough to construct a valid call.

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 ('Execute one WRITE endpoint'), the resource ('catalog'), and the action class ('create or update data'). It also explicitly distinguishes itself from siblings: 'Irreversible operations live in ms_delete_method, reads in ms_call_method.' This makes the tool's purpose unambiguous and differentiates it from the most similar alternatives.

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 when to use this tool (for write endpoints) and when not to (irreversible operations go to ms_delete_method, reads to ms_call_method). It also states a critical prerequisite: 'Requires confirm_write=true; nothing is sent without it.' This is clear, actionable guidance for an agent deciding between 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 signal a mutating, open-world operation, and the description adds method restrictions, the mandatory confirm_write guard, and the return/error envelope. This gives an agent the key behavioral guardrails beyond what readOnlyHint/openWorldHint 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?

The description is compact and front-loads the core purpose before a clear Args block. The only minor redundancy is repeating 'confirm_write must be true' in both the prose and the parameter list; otherwise it is lean.

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 6 parameters, this description is largely complete: it names the target API, allowed methods, path format, host override, query/body, confirmation gate, and return envelope. It could add a note about auth or preconditions for arbitrary raw writes, but 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 carry parameter meaning, and it does: it explains method values, path format, host default, query/body JSON nature, and confirm_write requirement. Every parameter in the schema is accounted for with usable semantics.

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: 'Create or update data at ANY path, including paths not in the catalog.' This clearly distinguishes ms_write_raw from catalog-bound siblings and the sibling delete/read raw tools. The allowed methods (POST, PUT, PATCH) further pin down the operation.

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

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

It gives concrete invocation constraints: POST/PUT/PATCH only, confirm_write must be true, and non-catalog paths are supported. However, it never explicitly says when to prefer this over ms_write_method, ms_call_method, or ms_delete_raw, leaving 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.