Claim a SimpleFIN setup token

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that the token is one-time, that the exchange yields a permanent Access URL, and that the URL is stored. It also warns of the single-claim constraint. Yet it omits possible side effects (e.g., overwriting existing stored URLs) and error behavior, leaving some ambiguity.

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 with no unnecessary words. The first sentence conveys the action, source, and result; the second delivers a critical limitation. Every word 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 a simple one-parameter tool with no output schema, the description covers the source of the token, the transformation, storage, and the single-use constraint. It lacks explicit mention of the function's return value (e.g., whether it returns the permanent Access URL) and error cases, but these are not critical for basic usage.

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 already fully describes the setupToken parameter. The tool description adds context by stating the token is Base64 and originates from 'bridge.simplefin.org/simplefin/create', plus underlines its one-time nature. This enhances understanding beyond the schema's baseline description.

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 action: 'Exchange a one-time Base64 setup token... for a permanent Access URL and store it.' This clearly differentiates from sibling tools like connection_status, list_accounts, and get_transactions, which deal with status and data retrieval rather than initial setup.

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 phrase 'Run this once to connect' provides clear usage timing, indicating this is the initial setup step. Additionally, the note 'a setup token can only be claimed a single time' warns against re-use. However, it does not explicitly name alternative tools or conditions under which this tool should not be used.

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