authenticate

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 covers the two authentication paths, credential handling (used once, not stored), and the optional MFA code. It doesn't specify session duration or error behavior, but for an authentication tool, the key behaviors are adequately described.

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 two sentences, front-loaded with the main purpose. No unnecessary words or repetition. Every sentence provides essential information, making it highly concise and well-structured.

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 has 3 parameters, no output schema, and no annotations, the description is fairly complete. It explains the two login paths, credential handling, and MFA. It could mention what happens on authentication failure or what the output looks like, but for the complexity level, it is 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: email and password are not required when Hermes brokers the login, and MFA code is used if prompted. This goes beyond the schema descriptions, adding conditional logic and usage nuance.

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 clearly states the tool's purpose: logging in to FreeTaxUSA. It specifies the two distinct authentication modes (Hermes-brokered vs. direct email/password), making the purpose precise and unambiguous.

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 explains when to use email/password (when Hermes is not configured) and when not to (when Hermes is configured). It also mentions that credentials are used once and never stored. While it doesn't explicitly list when-not-to-use alternatives, the context is clear enough for an agent to decide.

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