login

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

With no annotations provided, the description carries full behavioral burden and does well: explains the browser opens, user must click 'Authorize', API key is delivered to client and persisted to ~/.misarreach/config.json. Discloses the credential storage side effect. Could add what happens on failure/cancel but covers the key concerns.

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?

Three sentences, no fluff, front-loaded with purpose. The first sentence establishes the core CTA clearly. Slightly redundant elaboration of the flow but each sentence earns its place.

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 an auth tool with zero required params and no output schema, the description covers the flow, side effects, and persistence adequately. Combined with full schema coverage, the agent has enough to invoke correctly. Minor gap: no mention of success/failure return behavior or how the agent knows auth succeeded.

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%, all three params (port, force, app_url) are described in the schema. The description adds context around port range and the force behavior (issues a new key) but doesn't materially exceed the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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?

Clear verb+resource: 'Authenticate with your MisarReach account via browser.' Explicitly distinguishes from API key copy-paste flow and explains the OAuth-like browser interaction. Distinct from sibling tools (logout, auth_status), making it 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?

States when to use it (first-time auth or when re-authenticating) via the force parameter description. However, it doesn't explicitly compare against logout/auth_status or explain when NOT to use it (e.g., when credentials already present). Context is implied but exclusions are not stated.

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