list-actor-ownership

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the output semantics: each row reports the effective level and its source ('explicit' or 'inherited'), and it notes that the actor's default is reported as defaultPermission. It also clarifies a subtle edge case (distinguishing explicit NONE from absence of an entry). This is substantial transparency beyond the bare 'list' action, though it does not discuss side effects, authentication, or rate limits.

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 a single paragraph that front-loads the core purpose and then explains the output details and the key distinction it enables. Every sentence contributes useful information without redundancy. It is slightly longer than minimal but remains efficient given the complexity of the ownership model it clarifies.

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 read-only list tool with no output schema, the description explains the output format (rows with effective level and source), the meaning of the source field, and the defaultPermission reporting. It also addresses a common misinterpretation. It does not mention pagination, result limits, or error cases, but for this tool's scope, the information provided is sufficient for an agent to call it and interpret the result correctly.

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?

The input schema already provides 100% coverage with clear descriptions for both parameters (actorIdentifier and playerIdentifier). The description does not add new information about the parameters themselves, but it does tie them to the output semantics by implying how filtering by actor or player affects the rows shown. Since the schema covers the parameters, a baseline of 3 is appropriate, and the description adds only marginal value here.

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 states a specific action (list), a specific resource (actor ownership permissions), and the exact information returned (which players have what access levels, including the effective level and its source). It clearly distinguishes itself from the sibling set-actor-ownership by focusing on reading rather than writing, and it goes beyond a generic 'list' by explaining the explicit vs. inherited distinction.

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 description provides a concrete use case: 'Use it to tell an explicit NONE — a stored deny that overrides a permissive default — from a player who simply has no entry.' This gives clear guidance on when the tool is valuable. It does not explicitly name alternatives or exclusion criteria, but the context of the sibling set-actor-ownership makes the read/write distinction obvious, so a 4 is appropriate.

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