login

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

The description details the behavioral flow: detecting login form, retrieving credentials, filling and submitting, handling MFA/2FA, and returning page content. This goes beyond the annotations (readOnlyHint=false, openWorldHint=true) by explaining the side effects (credential retrieval, cookie storage via session parameter). However, it does not mention potential failure modes or fallback behavior.

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 and well-structured, with the main purpose front-loaded. It uses bullet points for requirements and return value, making it easy to scan. Every sentence adds value without extraneous information.

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 (login with MFA, credential management) and the presence of an output schema, the description adequately covers the process, requirements, and return type. It could be more complete by addressing error handling or the scope of login form detection, but it provides sufficient context for an agent to use the tool effectively.

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?

With schema description coverage at only 33% (only session is described in the schema), the description fails to compensate for the missing parameter details. The url parameter is implied but not explicitly described, and the cookies parameter is not mentioned at all. This leaves ambiguity for the agent about the format and purpose of these parameters.

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 'Auto-login to a website using 1Password credentials,' specifying the verb (auto-login), resource (website), and scope (using 1Password). This distinguishes it from sibling tools like fetch (simple retrieval) and submit (form submission), as it handles the entire authentication flow including credential retrieval and MFA.

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 clear usage context by outlining the prerequisites (1Password CLI installed and authenticated) and the process (detect form, fill, submit, handle MFA). It implicitly differentiates from alternatives by focusing on login with 1Password, though it could explicitly state when to use this tool over fetch or auth_lookup.

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