rx_help_toc

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false. The description adds useful output context beyond annotations: it returns top-level sections or section contents including article file names, which helps an agent understand what the call produces.

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, front-loaded sentences with no filler: the first defines the tool, the second gives routing guidance, and the third states read-only behavior. Every sentence earns its place.

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 read-only TOC tool with full schema coverage and no output schema, the description is complete enough. It explains purpose, usage relative to a sibling, and the shape of returned data, while annotations and schema cover the rest.

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 schema already documents both depth and section parameters in detail. The description aligns with the section parameter semantics but does not add meaning beyond what the schema provides, making the baseline 3 appropriate.

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: help table of contents for Directum RX, returning top-level sections or section contents with article file names. It also names the sibling tool rx_help_search, so an agent can distinguish this from keyword search without opening either schema.

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 says to use this when rx_help_search does not find what is needed, to understand which section to search, or to show what exists in the help. This gives clear when-to-use guidance and names the alternative tool directly.

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