nexus_council

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

With no annotations, the description carries the burden of revealing behavior, and it does so meaningfully: participants respond in parallel, see all prior contributions, run in rounds, and Opus ultimately decides. It also discloses that research mode uses tools such as file/web search and cross-references findings. It does not cover cost, auth, or side effects, but the core execution model is transparent.

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?

Every sentence earns its place: the core action, mode explanations, parallel round behavior, and use-case list are all useful and non-redundant. It is front-loaded with the verb and outcome, and it remains compact despite covering a complex tool.

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 complex council tool with no output schema and five parameters, the description lays out the workflow, participant interaction model, mode variations, and intended use cases. It leaves out return-value details, but 'Opus makes the final decision' sufficiently communicates the outcome. The description is complete enough for an agent to decide whether to call it and roughly how it will behave.

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 baseline is 3, but the description adds value by explaining what each mode means behaviorally (build collaboratively, challenge adversarially, investigate with tools). This supplements the enum's short schema descriptions with operational detail, particularly the cross-referencing aspect of research mode.

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 clearly identifies the action ('convene a multi-model council') and the resource ('AI agents deliberate in rounds... Opus makes the final decision'). It also defines three distinct modes—DISCUSSION, EBATE, ESEARCH—and lists concrete use cases, making the tool's purpose unmistakable and distinguishing it from the subtool/sibling tools.

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 claims the tool for specific use cases: 'Use this for architecture decisions, code reviews, security audits, complex analysis.' This provides clear context for when to invoke it, though it does not explicitly name alternatives or state when not to use it.

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