Verify a 6-digit Client Portal sign-in PIN to exchange it for a session, enabling access for practices that email a code instead of a link. Single-use.
Exchange a 6-digit Client Portal sign-in PIN for a session, for practices that email a code instead of a link. Single-use.
| Name | Required | Description | Default |
|---|---|---|---|
| pin | Yes | ||
| Yes | The address the PIN was sent to. |
Changes observed during successful MCP inspections.
v0.4.2Input schema / properties / email / patternPrevious value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as non-read-only and non-idempotent Tweaking. The description adds the important behavioral trait that the PIN is single-use, meaning it is consumed and cannot be reused. This goes beyond the idempotent hint and clarifies a meaningful side effect.
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 short sentences with no filler. It leads with the core action and quickly states the single-use constraint, making it easy for an agent to parse and act on.
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?
The tool is simple with only two required parametersebbw Nev, and the description conveys the core exchange behavior. However, it does not specify what the returned session looks like, how errors such as invalid or expired PINs are handled, or any additional constraints. Given there is no output schema, these omissions leave the agent with some uncertainty.
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 schema documents email via its description, but pin only has a regex pattern. The description reinforces that the pin is a 6-digit code sent via email, which helps clarify the pin field. However, it does not fully compensate for the missing pin description or explain the relationship between params beyond what the schema already shows.
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: exchanging a 6-digit Client Portal sign-in PIN for a session. It also distinguishes this tool from link-based login flows by noting it is for practices that email a code instead of a link, and adds the single-use nuance.
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 gives a clear context for use: practices that email a code rather than a link. It does not explicitly name alternatives like request_sign_in_link or verify_sign_in_token, but the condition is specific enough to guide selection without exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.