rsi_learn

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: responsibility for lesson authoring lies with the host (RSI will not generate it), and gated actions return not_in_phase with a message to redirect. It does not say which actions mutate persistent state, what promote or teach_record actually change, or whether any operation is reversible.

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 action categories are front-loaded, which is good, but the entire content is duplicated in Chinese, roughly doubling length with zero new information for a single locale-driven audience. No sentence is wasted individually, yet the deliverable is twice the necessary size.

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?

This is a 13-action dispatcher with 25 parameters, nested objects, no annotations, and no output schema — the highest-burden case — yet the description explains only the teach loop and the pack trio. The audit pipeline (audit_start → audit_probes → audit_report → audit_finish), extract, promote, skip, and rubric are unaddressed, leaving an agent unable to sequence most of the tool's surface.

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 80%, so the baseline is 3 and the schema already documents the individually described fields. The description adds only indirect hints by naming some action values in prose (teach_record, pack_list, pack_open, pack_done) but says nothing about scope/scope_id pairing, pack_id vs id aliasing, or the payload object.

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 noun list ('Teaching / audit / closeout learn / promote / reading-pack actions') rather than a single clear verb+resource, and it never says outright that this is a multi-action dispatcher for the RSI learning lifecycle. The second sentence does name concrete actions (teach_record, pack_list/pack_open/pack_done), which gives partial specificity, but nothing distinguishes this from siblings like rsi_recall or rsi_review.

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

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

It gives real procedural guidance for one path: 'The host agent writes the lesson (Catch→Teach→Fix) then teach_record; RSI does not write the lesson.' That tells an agent who must supply content. But for the other nine-plus actions (audit_start/probes/report/finish, extract, promote, skip, rubric) there is no when-to-use, ordering, or alternative-tool guidance.

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