Run account tool

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the two supported tool names and the exact input payload each expects ({ subreddit } vs {}), which is not recoverable from the schema. It stops short of describing what the lookup returns or any per-platform failure modes.

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 compact sentences: the operation and its variants come first, the usage trigger second. No filler, and the per-tool input shapes are parenthetically inlined rather than given their own bloated section.

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?

There is no output schema, so the description should ideally say what a lookup yields (a list of flairs with ids, a list of boards with ids) so the agent knows how to feed the result into create_post. That return-shape gap, plus the undocumented accountId, leaves it adequate but incomplete for a dispatcher 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 coverage is only 33% and the `tool` parameter has no enum, so the description carries the burden of enumerating valid values and their payload shapes — it does this well for `tool` and `input`. `accountId` remains undocumented in both schema and description, which keeps it below a 5.

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 ('Run a per-account lookup') and enumerates the concrete operations available (reddit-flairs, pinterest-boards) with their input shapes. It is distinguishable from siblings like list_account_tools, though that relationship (this is the executor for the tools that tool lists) is only implied via the schema's parameter description rather than stated.

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?

'Use before creating posts that need a flair or board id' gives an explicit triggering condition and ties the tool to a downstream action. It does not state when-not-to-use or clarify that a prior list_account_tools call is required to obtain a valid tool name, leaving that sequencing to inference.

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