admin_organizations

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

Locks the SUPER_ADMIN role requirement, which is a security/authorization disclosure. Lists what data comes back (owner info, plan, counts, ANAF token status). However, with no annotations provided, the description carries full burden; it doesn't mention whether this is read-only (implied by 'List'), sort behavior, or response pagination shape, though listing is safely inferable as non-destructive.

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 sentences, zero filler. Front-loaded with the core action, then the authorization gate, then the returned-data value. Every clause earns 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?

For a straightforward read-only listing tool with full schema coverage, the description covers the essentials: scope, authorization, pagination/filtering, and returned fields. Minor gaps exist (response format/sort order) but no output schema exists, and for an admin list tool this is acceptably complete.

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 100%, so all five parameters already have descriptions. The tool description adds the search scope ('name or owner name/email') and the specific data fields returned, which enriches meaning beyond the raw schema. This is a solid baseline case where the schema carries most weight and the description complements it.

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?

Description uses a specific verb+resource ('List all organizations on the platform') with pagination and filtering, and clearly targets SUPER_ADMIN only. It distinguishes itself from related admin tools (admin_stats, admin_users) by listing the specific data fields returned.

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?

Clearly states SUPER_ADMIN-only access constraint, which is important usage guidance. However, it doesn't explicitly contrast with sibling admin tools like admin_stats or admin_users, nor state when NOT to use it. The role restriction is a clear boundary condition but no alternatives are named.

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