ksef_auth_init

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

Annotations only include readOnlyHint=false, which signals mutation. The description goes beyond that by revealing the multi-step OAuth-like flow and the final output (JWT access + refresh), giving the agent a clear picture of side effects: it will initiate network calls and create a session state. This is meaningful behavioral context beyond the annotation.

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 compact, front-loads the core verb and resource, then gives the exact flow in a short chain. Every sentence is useful and no filler exists. The flow notation is concise and scannable for an agent.

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 session-initiation tool with 3 self-describing optional parameters and no output schema, the description adequately covers the main behavior, flow, and input sources. It does not mention error cases, token validation, or session timeout behavior, but those are not essential for selecting and invoking the tool 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 covers 100% of parameters with descriptions and defaults, including the environment enum. The tool description adds the general concept that parameters can come from env vars, but it does not add detailed semantics beyond the schema. Per calibration, baseline 3 is appropriate when schema coverage is high.

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 verb and resource: 'Rozpocznij sesję KSeF' (start a KSeF session) using an authorization token, and explicitly mentions API v2. It distinguishes the action from sibling tools like ksef_auth_status or ksef_auth_terminate by naming the session-starting flow, though it does not directly name a sibling for contrast.

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 clearly implies this is the entry-point tool for starting a KSeF session and outlines the sequential flow (challenge → ksef-token → token/redeem → JWT). It gives context about when to use it, and the alternative options of passing arguments or env vars. It does not explicitly state when not to use it or name alternatives, but the flow structure provides solid usage guidance.

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