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

Adds critical behavioral context beyond annotations: warns that key enters chat transcript, explains storage details (~/.marketplace-mcp/cabinets.json with chmod 600), and confirms 'never echoed'. 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?

Well-structured with clear warning, bullet-like parameter descriptions. Slightly lengthy due to examples and safety emphasis, but 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?

Complete for a credential-adding tool: covers purpose, usage, parameter semantics, security considerations, and storage location. Output schema exists, so return values are not needed.

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 fully explains all three parameters: credentials (with examples for Ozon and WB), name (optional label and fallback behavior), and the boolean safety flag. Adds meaning beyond the input 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 'Add or update a cabinet (a named set of API credentials)', using specific verb and resource. It distinguishes from sibling tools like ms_remove_cabinet by focusing on creation/update.

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 provides when-to-use vs alternatives: mentions installer as safer alternative and requires the safety flag i_understand_key_goes_to_chat=true. No misleading statements.

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?

The description goes beyond annotations by explaining the exact behavior: read endpoints run immediately, write/destructive require extra flags, and nothing is sent for destructive if not confirmed. It also describes the return format (JSON envelope with ok, status, data or error). 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: it starts with the core purpose, then separates read vs write/destructive behavior, and lists parameters. It is slightly verbose but each sentence adds value. Could be tightened slightly but effective.

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 as a generic endpoint executor, the description covers the flow for read, write, and destructive operations, parameter purposes, and the return format. With an output schema present, the return description is sufficient. No gaps identified.

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: operation_id (from catalog), path_values (for placeholders), query (query-string), body (JSON), confirm_write (required for write/destructive), and i_understand_this_modifies_data (required for destructive). This provides complete meaning beyond 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 clearly states it executes a catalog endpoint by operation_id, distinguishing it from sibling tools like ms_call_raw and ms_search_methods. It also specifies that read endpoints run immediately, while write/destructive require confirmation.

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 usage guidance: read endpoints run immediately, write endpoints need confirm_write=true, and destructive endpoints require both confirm_write and i_understand_this_modifies_data. It also references `{svc}_search_methods` to find operation_id, giving context on when to use this tool and how to select the correct 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?

The description goes beyond annotations by detailing safety inference per HTTP verb, the return format (JSON with ok, status, data), and the need for confirmations. This adds significant context that annotations (readOnlyHint, destructiveHint) only partially cover.

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: purpose first, then safety, args in a list, return format. No superfluous sentences; every line 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?

The description covers the tool's purpose, safety behavior, parameter details, and return format. It is complete for a raw API caller, referencing confirmation rules appropriately.

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

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

Despite 0% schema description coverage, the description provides clear, standalone explanations for each parameter (method, path, host, query, body, confirm_write, i_understand_this_modifies_data), adding meaning beyond the schema's titles 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 executes ANY endpoint, even those not in the catalog, providing full API coverage. This distinguishes it from siblings like ms_call_method (which presumably handles cataloged endpoints), making its purpose unambiguous.

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

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

The description explains safety inference from HTTP verbs and references confirmation rules similar to {svc}_call_method. It implies use for uncataloged endpoints but does not explicitly state when to prefer this over siblings or exclude certain 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 declare readOnlyHint true. The description adds that it only reports which variables are set and provides the exact return JSON format, adding context 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?

Three sentences, each essential: action, limitation, return format. Front-loaded with verb and resource. 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 parameterless tool with output schema described inline, all necessary information is present. The description fully covers behavior and return structure.

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 exist, so schema coverage is 100%. The description need not add parameter info, and is appropriately silent. Baseline for 0 params is 4.

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 checks for required credentials in the environment, specifying that it does not reveal secret values. It uniquely distinguishes itself from sibling tools, which are all CRUD or business operations.

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 before making authenticated requests, but does not explicitly state when not to use or provide alternatives. However, given no other auth-checking tools exist, it's sufficiently 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?

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 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 indicate readOnlyHint=true. The description adds valuable behavioral details: automatic handling of offset, cursor, and other pagination styles, a default max_items cap of 10k, and a structured return format. 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: a purpose sentence, a line on styles handled, and a bullet-like args list. It is front-loaded and efficient, though the args list could be more visually structured.

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 core functionality (pagination handling, output format) but omits error handling, edge cases (e.g., invalid operation_id), and details on the catalog. For a complex tool, it is mostly adequate.

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 explains each parameter (operation_id as read endpoint, limit as page size, max_items as hard cap, items_path as override, etc.), adding meaning beyond the bare schema. However, it lacks examples or constraints for valid 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 tool auto-paginates a read endpoint and returns all rows, distinguishing it from sibling tools like ms_call_raw or specific ms_get_* tools by focusing on generic pagination for any read endpoint from the catalog.

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

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

The description implies usage for read endpoints needing pagination but lacks explicit guidance on when not to use or alternatives (e.g., if a specific endpoint tool is more efficient). No exclusion criteria are 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 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 indicate readOnlyHint=true, and the description does not contradict it. The description adds details about the return format (JSON list with specific fields), which goes beyond 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 very concise: one line for purpose, one for parameter, one for return. Front-loaded with the core action. No unnecessary 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 low complexity (1 param, output schema exists), the description adequately covers what the agent needs: what it does, the parameter, and the return format. It references the sibling tool for section names, completing the context.

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. It explains the section parameter, gives its source (list_sections) and an example, adding 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 the action ('List all endpoints') and the resource ('in one section'). It distinguishes from sibling tools like ms_list_sections that list sections themselves.

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

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

The description provides a clear example of the section parameter and references where to find valid section names (see {svc}_list_sections). It lacks explicit guidance on when not to use or alternatives but is informative 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?

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 confirm readOnlyHint=true. Description adds value by detailing return JSON structure and stating 'Secret values are never returned', which is critical behavioral info 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?

Two concise sentences with no fluff. Returns valuable info upfront: purpose, JSON structure, and security note.

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?

Simple tool with no parameters and output schema present. Description fully covers return format and a key constraint (no secrets), making it complete for effective usage.

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 defined; baseline is 4 due to high schema coverage (100%). Description adds no extra parameter info but is effective given 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?

Description clearly states 'List configured cabinets' with specific verb and resource. Distinguishes from sibling tools like ms_add_cabinet, ms_remove_cabinet, and ms_use_cabinet by focusing on read-only listing.

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?

Implies usage context (marketplace) but no explicit guidance on when to use vs alternatives. No exclusions or when-not scenarios 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 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, which the description reinforces by indicating it's a read-only orientation tool. No contradictions; description adds context about its purpose beyond 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?

Two sentences with key info front-loaded ('The big picture...'). Every phrase earns its place, no 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 tool's simple nature and presence of an output schema, the description fully explains behavior and usage. No 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%, but the description explains the optional 'entity' parameter clearly: with no args shows full map, with entity filters methods. This compensates well for the lack of 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 clearly states it provides a map of business entities and methods, distinguishing it from sibling tools as a navigational/orientation tool. It uses specific language like 'the big picture' and 'orients you fast'.

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 states when to call with no args versus passing an entity name, and advises using it before guessing. This provides clear guidance on usage and 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?

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 mark destructiveHint=true, but the description adds transparency by noting the side effect that another cabinet becomes active if the removed one was active. This goes beyond the structured fields.

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

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

The description is extremely concise with two sentences for the main functionality and one line for the parameter. Every sentence adds value, and the key 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?

The description covers the core action and a key side effect, but does not explain prerequisites, error conditions, or what 'active' means in this context. With an output schema present, return values need not be detailed, but more behavioral depth would improve completeness.

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

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

With 0% schema description coverage, the description compensates by stating 'name: the cabinet to remove.' This provides meaning beyond the schema's property definition of just 'Name'.

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 'Delete a stored cabinet' using a specific verb and resource. It distinguishes from sibling tools like ms_add_cabinet and ms_use_cabinet by focusing on removal, and adds context about the active cabinet side effect.

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 does not provide explicit guidance on when to use this tool versus alternatives like ms_list_cabinets or ms_use_cabinet. It implies usage when deletion is desired but lacks when-not or alternative recommendations.

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=false, so the safety profile is clear. The description adds that it returns a JSON list, but no further behavioral traits beyond what 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 concise with three front-loaded sentences covering purpose, arguments, and return type without any 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 output schema exists and parameter count is low, the description provides enough context: clear purpose, parameter semantics, and return type. It is complete for this 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 adds semantic meaning: query is 'free text' with examples, and limit is 'max results (1-50)'. This compensates well for the schema gap.

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

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

The description clearly states 'Search the endpoint catalog by keyword' with specific examples, and this purpose is distinct from sibling tools like ms_describe_method or ms_call_method.

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

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

The description implies usage for searching endpoints by keyword, with examples in Russian and English, but does not explicitly provide when-not-to-use or name alternative tools.

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 (idempotentHint=true, destructiveHint=false), description reveals key validation, local save with secure permissions, no echo, and chat transcript exposure risk. 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?

Well-structured with front-loaded purpose, warning, args list, and post-condition, but slightly verbose. Could trim alternative mention, though useful.

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

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

Complete for tool complexity: includes purpose, arguments, prerequisites (boolean flag), behavior, and success outcome. Output schema exists so return details not needed.

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 coverage, the description provides detailed parameter meanings: credentials dict, cabinet selection logic with defaults, and the required boolean guard. Fully compensates for lack of 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 explicitly states 'Change / rotate the API key from chat' with a specific verb and resource. It clearly distinguishes from alternative (installer) and implies use cases like expired or leaked key.

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?

Provides explicit when-to-use (key expired/leaked) and when-not-to-use (prefer installer to avoid key in chat). Also advises using scoped keys and rotation, guiding agent on best practices.

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 the tool is idempotent and not read-only. The description adds crucial behavioral context: switching the active cabinet changes credentials for subsequent calls, which is not conveyed by annotations alone.

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

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

The description is extremely concise: one sentence for purpose, then a structured Args section. Every word is necessary, no 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 simple tool with one required parameter and an existing output schema, the description provides all necessary context: purpose, parameter meaning, and prerequisite knowledge. 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?

Despite 0% schema description coverage, the description adds full meaning for the single required parameter: it specifies that 'name' is the cabinet to activate and directs the agent to list cabinets for valid values. This compensates entirely for the schema gap.

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

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

The description clearly states the tool switches the active cabinet and that subsequent API calls use its credentials. This is a specific verb and resource, distinguished from sibling tools like ms_add_cabinet or ms_list_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 references {svc}_list_cabinets to obtain the cabinet name, providing clear context on prerequisites. No explicit when-not or alternative tools are mentioned, but for this simple tool the guidance is adequate.

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