list_discussion_posts

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no behavioral details about the tool itself—neither its operation nor its effects. The only extra info is that it is blocked, which is a status, not a behavior. It does not contradict annotations but provides no meaningful behavioral context.

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 description is extremely short (a single sentence), which could be praised for conciseness, but it omits essential information. The front-loaded 'Blocked' is efficient, but the rest is a redirect. It is under-specified rather than effectively concise, as it fails to describe the tool's purpose or usage.

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 tool with 3 parameters, no output schema, and no parameter documentation, the description is completely inadequate. It neither explains what the tool does, how it behaves, nor how to call it. The only useful content is the blocking notice and alternative pointer, but that does not make the definition complete for using this tool.

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 0%, so the description must explain parameters. It mentions none of the three parameters (discussion_id, limit, offset) nor any expected values or semantics. The description gives zero assistance in understanding how to populate or use the parameters.

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 only says 'Blocked: Moodle can mark posts; use the confirmed inspect flow.' It never states what the tool actually does (list discussion posts). It is essentially a block notice, not a purpose definition. There is no verb indicating the tool's function, and it fails to distinguish the tool from siblings based on functionality.

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 tells the agent not to use this tool ('Blocked') and directs to the 'confirmed inspect flow,' which maps to sibling tools 'inspect_discussion_posts' and 'preview_inspect_discussion_posts.' This is clear when-not-to-use guidance and points to the correct alternative. However, it doesn't explain under what conditions this tool would be usable, only that it is currently blocked.

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