polaris_tribes

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 that 'archive' is a soft delete ("tribe stays queryable, status becomes ARCHIVED"), that lists are cursor-paginated with a returned nextCursor, and that 'overview' reads the Insights read model. Auth requirements and rate limits are unstated, keeping it out of the top band.

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 one-line purpose followed by a compact action/parameter table and a single-line JSON shape. Every sentence earns its place. Minor cost is that the Tribe JSON shape line is dense, but it is load-bearing given there is no output schema.

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 five-action polymorphic tool with no annotations and no output schema, the description covers the action semantics, the mutation side effect of archive, the pagination contract, and the return object shape. Missing only edge cases such as error behavior or permissions on create/archive.

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% across 8 parameters, so the description must compensate and it does: it maps every parameter to the action that consumes it (list: limit/cursor/all_pages; get/archive/overview: tribe_id; create: name/description; archive: reason), states which are optional, and even gives the limit range (1-200). This is meaning fully beyond the bare schema.

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 concrete verb+resource and, crucially, defines the resource's place in the topology ("the topology level that groups squads"), which implicitly distinguishes it from the polaris_squads sibling. The action enumeration reinforces the scope. It falls short of 5 because it never names the sibling it is not.

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 action list with required parameters gives clear task-level routing inside the tool, so an agent knows which action to pick. However, there is no guidance on when to prefer this tool over polaris_squads or polaris_insights (the 'overview' action reads the Insights model), and no prerequisites are stated.

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