bx24_batch

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

No annotations are present, so the description carries the full behavioral disclosure burden. It does disclose that earlier results can be referenced with $result[key], which implies ordered execution, and mentions REST 1.0 + 3.0 compatibility. However, it omits error behavior, partial failure semantics, response structure, and destructive-command concerns beyond what the schema already shows.

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 core purpose is front-loaded in a single, clear sentence, followed by the key reference mechanism. The bilingual keyword list is somewhat redundant for an AI agent and could be trimmed, but it does not significantly bloat the description. Overall it is compact and 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 the essence of batching and the $result reference mechanism, and the schema fully documents cmd, halt, and confirm. However, with no output schema and no annotations, the agent is left without information about the batch response format or how execution failures are surfaced. For a generic execution wrapper, this is a notable gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concise general rule for referencing results ($result[key]) that complements the schema's example. Yet the schema already contains the same reference syntax, so the description provides only marginal additional parameter insight.

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-resource pair: 'combine multiple REST calls into one request' and identifies the exact Bitrix24 method ('batch'). It clearly distinguishes this generic batching tool from the domain-specific sibling tools. The bilingual keyword list reinforces meaning rather than obscuring it.

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 the use case: use this tool when multiple REST calls need to be combined into a single request. However, it does not explicitly state when not to use it, which sibling should be chosen instead, or any prerequisites such as REST method compatibility. The hybrid RU/EN phrases add searchability but no direct usage exclusions.

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