cigchat_subscriber_update_order_status

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully discloses that the tool 'Delivers a real message to a person' (a significant side effect) and requires the 'Manage Flow' scope. However, it omits other behaviors such as whether status changes are reversible, idempotency, error conditions, or the response format, leaving gaps in transparency.

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

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

The description is relatively compact and front-loads the core action and allowed values. It includes the HTTP endpoint and scope requirement without excessive fluff. The phrasing is a bit awkward (running the side-effect statement into the same sentence as the endpoint), but it earns its place by adding the crucial real-message warning.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It fails to clarify key parameters like order_id and user_ns, does not describe return values or failure modes, and leaves the 'Delivers a real message' behavior ambiguous (to whom, under what conditions). The provided status list and scope info help, but the lack of detail makes it risky for an agent to invoke correctly in all contexts.

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 description coverage is only 33%, with only the 'status' parameter having any description. The description adds value by enumerating the valid status values for 'status', but it does not explain the semantics or format of 'order_id' or 'user_ns', which remain undocumented in both the schema and the description. This is insufficient for low schema 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?

The description clearly states the action ('Update order status') and provides the complete list of allowed statuses, which gives a specific verb and resource. It is somewhat muddied by the cryptic 'Delivers a real message to a person' phrase and does not explicitly distinguish from sibling tools like cigchat_shop_orders_update, but the tool name and status list make the purpose understandable.

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

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

No explicit guidance is provided on when to use this tool versus alternatives such as cigchat_shop_orders_update or cigchat_subscriber_update. The description mentions a scope requirement and the side effect of delivering a real message, which implies caution, but it does not state when to choose this tool or when not to.

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