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

There are no annotations, so the description must carry behavioral context itself. It does convey that untriaged ideas are operator-scoped, triaged ideas are company-scoped, and include_promoted controls whether Playbook-promoted ideas appear. A minor omission is that it doesn't explicitly state read-only/no-side-effect behavior, but the 'List' framing and scoping notes provide adequate transparency for a read-only tool.

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 compact and every sentence earns its place: scope, filters, usage, and sibling routing. It front-loads the most important scoping fact and avoids repeated preamble.

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?

Given that all four parameters have detailed schema descriptions and no nested objects exist, this description provides enough context to select and invoke the tool confidently. It covers what the tool returns conceptually, which statuses to filter on, the operator-vs-company scope, the promoted toggle, and the related sibling operations, leaving no significant ambiguity.

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?

With 100% schema coverage, the parameters are already well documented, so the baseline is 3. The description adds semantic value beyond the schema by grouping 'new' and 'parked' as untriaged/operator-scoped and 'triaged' as company-scoped, and by reinforcing the meaning of include_promoted and the default status.

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 verb and resource ('List Ideas') and distinguishes the two scopes: untriaged ideas are 'for the operator' and triaged ideas belong to the current company. It also directly names capture_idea and triage_idea, which are the related sibling actions, making it easy to tell this read tool apart.

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?

It explicitly says to use the tool when you need to see captured Ideas, which defines the intended invocation context. It then routes creation to capture_idea and assignment to triage_idea, giving clear when-not-to-use guidance and alternatives.

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