raggy_threads

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 does convey the key dual-mode behavior and the conditional dependency on session_id for action=get, and verbs like 'browses' and 'retrieves' imply a read-only operation. However, it omits return-format details, how sessions are defined/created, and any side effects, so an agent must infer the safety profile.

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?

Two sentences with no filler: the first front-loads the purpose with illustrative examples, and the second compactly explains the action enum. Every clause 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 moderately complex dual-mode tool, the description covers the core invocation logic well and the schema documents all five parameters. Gaps remain because there is no output schema or annotations: the return values and the definition of a 'session' boundary are left to inference, though the verbs 'browses' and 'retrieves' make the outputs largely predictable.

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 even without extra description input. The description adds only marginal semantic value beyond the schema: it links action=get to 'all memories for one session_id' and ties limit/since to the act of browsing 'recent sessions', but the schema already documents each parameter and the conditional requirement on session_id.

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 use case ('session-based queries') and two concrete example queries, then maps each mode to a distinct verb-resource pair: action="list" 'browses recent sessions' and action="get" 'retrieves all memories for one session_id'. The session-based scope differentiates it from siblings like raggy_recall and raggy_timeline, which target individual memories or chronological events rather than grouped sessions.

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 explicitly frames when to use the tool ('Use for session-based queries like...') and gives two natural-language examples an agent can pattern-match against the user's request. However, it does not name alternatives or state when not to use it, leaving the agent to infer the boundary against siblings like raggy_timeline.

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