aps_capability_evaluate_authority

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

With no annotations, the description carries full weight for behavioral transparency. It states the subject signs a request and the gateway decides permit/deny, but fails to disclose side effects, error conditions, rate limits, or authentication requirements. The disclosure is basic but adequate for a single-purpose evaluation tool.

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 concise at three sentences, front-loading the purpose and protocol step. It uses technical terms (M1, M2, preimage) that are necessary for the domain but could be slightly more accessible. Overall, it is well-structured and earns its content.

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?

Given the tool's complexity (7 parameters, nested objects, no output schema), the description covers the main flow but omits details like what 'permit/deny' returns, how to construct the delegation chain, and what happens on failure. The schema descriptions help, but the overall completeness is average—adequate for a domain-expert agent but not fully self-sufficient.

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 description adds context by explaining that the request carries the sink's M1 (challenge), delegation chain, and authority-token preimage, which clarifies the role of key parameters beyond the schema. Schema description coverage is 71%, and the description compensates for missing top-level descriptions of authority_token and freshness_beacon by implying their use. This helps an agent understand how parameters relate in the protocol.

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 identifies the tool as a 'capability-token authority evaluation request (M2)' and explains the flow: the subject signs a request with the sink's M1, delegation chain, and revealed authority-token preimage. It clearly distinguishes from siblings like issue_challenge or mint_receipt by focusing on evaluation, but the technical jargon may obscure the core action for some agents.

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 does not provide explicit guidance on when to use this tool versus alternatives. It describes what the tool does but lacks context about prerequisites, when an agent should invoke it, or when to choose a different capability tool like aps_capability_issue_challenge or aps_capability_sign_effect.

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