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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavior: it returns the assistant's reply and, on AI service failure, raises a JSON-RPC error carrying {chat_id, ai_error} instead of a fake apology reply. That failure-mode disclosure is exactly the kind of context annotations cannot provide. It stops short of mentioning side effects like token spend or chat state mutation.

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

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

Three short sentences, front-loaded with the action, then the return value, then the error contract. No filler, and the clarification about error-vs-apology directly prevents a misread of failure output.

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

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

With no output schema, the description usefully covers both the success return and the failure shape. However, for a stateful tool taking an opaque chat_id, it leaves the prerequisite (where chat_id originates) and parameter meaning undocumented, so an agent still lacks enough to call it confidently from a cold start.

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

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

Schema description coverage is 0%, so the description must carry the load for both required parameters. It only obliquely hints that chat_id identifies an existing chat and message is the follow-up text; it gives no format, length, or content guidance and no indication of whether chat_id comes from a prior chat call.

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

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

States a specific verb and resource: 'Send another message to an existing repo chat', plus what it returns. The word 'another' distinguishes it from starting a fresh chat (the merjax_chat_with_repo sibling), though that sibling is never named explicitly.

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

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

Usage is implied rather than stated: 'existing repo chat' and 'another message' suggest it is the follow-up to an initial chat call, but the description never names merjax_chat_with_repo as the alternative or states when-not to use this tool. An agent must infer the routing.

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