pplx_council

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

With no annotations, the description carries the full burden and does well: it discloses the cost model (each council member = 1 Pro Search query, synthesis an extra Sonar 2 call), the Max-only model restrictions tied to subscription tier, the per-model chairman surcharge, and which models support the thinking toggle. It does not spell out rate limits or return shape, and the read-only nature is only implied, keeping it short of a 5.

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?

Front-loaded and well-organized with an IMPORTANT block, but there is real redundancy: the 16-model list appears three times (step 1, the models arg, and elsewhere) and the cost rule is restated. The Args section also repeats schema content the agent can already read, so a nontrivial share of the text does not earn its place.

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?

An output schema exists, so return values needn't be described. Combined with the cost/subscription gating, required confirmation workflow, and per-parameter notes, this is close to complete for a 6-parameter orchestration tool; only the missing guidance on choosing council vs. sibling research tools leaves a small gap.

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 compensate — and it largely does, explaining models (full list, default, Max-only exclusions), synthesize (false skips synthesis and saves a Sonar 2 call), thinking (which models toggle vs. always-on), chairman (default sonar, surcharge for non-sonar), and source_focus. Gaps remain: the chairman enum's 'auto' and 'deep_research' values are undocumented, and source_focus values are only parenthetically listed.

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 opening line states a specific verb+resource+mechanism: 'query multiple models in parallel, get synthesized consensus.' That cleanly distinguishes it from siblings like pplx_sonar, pplx_smart_query, and the single-model pplx_<model> tools, which return one model's answer rather than a synthesized council.

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?

Gives an unusually explicit precondition workflow (list models, check pplx_usage for subscription gating, confirm model count, disclose cost, get confirmation) and names the dependency tool pplx_usage. It is weaker on positional guidance against sibling alternatives (e.g., when to prefer pplx_deep_research or pplx_smart_query over a council), but the multi-model-consensus context is clear.

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