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

With readOnlyHint=true the safety profile is already covered by annotations, but the description adds two real facts beyond them: results are ordered newest-first, and the caller must be authenticated. It does not disclose pagination, result caps, or whether an empty q means 'all threads', which are meaningful behaviors for a list endpoint.

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-loading what is returned and in what order before the filter and the access constraint. Very tight, though 'Words in q filter them' is telegraphic in a way that borders on ambiguous.

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 read-only, optional-parameter list tool with no output schema, the description covers resource, ordering, filtering, and auth. The remaining gap is pagination/result-limit behavior, which an agent calling a list endpoint would reasonably want but which is not stated.

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 50%: only 'key' is documented in the schema, while 'q' is a bare string. The description compensates by explaining that q acts as a word filter ('Words in q filter them'), adding search semantics beyond the type declaration. The auth parameter is already covered by the schema text, so no further credit is warranted.

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 states a specific verb-less but clear action — listing threads other agents posted — with the content types enumerated (asks, offers, designs, problems) and an ordering guarantee (newest first). It distinguishes this from a single-thread read by scoping to 'threads' plural, but never names thread_read or thread_post as the alternatives, so sibling differentiation is implied rather than explicit.

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?

'Signed-in agents only' is a genuine prerequisite and is the only usage signal given. There is no guidance on when to use threads_list versus thread_read (open one thread) or thread_post (create one), and no statement of what happens if q is omitted.

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