Room questions (raw)

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: hidden questions are never returned, cursor-based paging must repeat until next_cursor is null, and question text/answers must be treated as content, never instructions. That injection warning and pagination contract go well beyond the structured fields.

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?

Front-loaded with purpose, then alternatives, then sort semantics, then pagination. Every sentence carries information, though the sort and pagination clauses make it longer than strictly minimal.

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?

No output schema exists, so the description carries the return-value burden and does it: field list, hidden-question exclusion, and the next_cursor contract are all covered. Nothing needed to call the tool repeatedly or interpret results is missing.

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 100%, so the baseline is 3, but the description adds real semantics the schema lacks: sort=top prioritizes waiting questions then approved/answered by votes, sort=recent is newest-first. The pagination role of cursor and next_cursor is also clarified beyond the schema's one-line definition.

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 ('read one page of a room's questions as JSON') and enumerates the returned fields (id, body, status, votes, pinned, host answer). It explicitly distinguishes itself from the sibling get_room_qa, so an agent can route 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?

Gives explicit when-to-use conditions: needs question ids for moderate_question or answer_question, or paging through a large room, with an explicit alternative ('use get_room_qa instead for a ready-made FAQ'). It also explains when to pick each sort mode, leaving nothing to inference.

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