set_token

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

With no annotations, the description fully covers behavioral traits: it warns that the token travels through the chat and is sent to the LLM provider, explains validation via a probe call, states that persistence is to credentials.json with mode 600, and that invalid tokens persist nothing. This comprehensively sets expectations.

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 longer than minimal but every sentence earns its place: purpose, privacy warning, CLI alternative, parameter usage, and behavioral details are all essential. It front-loads the core action and guidance, making it easy to scan.

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 4 parameters and no output schema, the description provides complete context: explains token validation, persistence details, privacy implications, and precise usage conditions. There are no gaps in understanding how to use the tool safely and 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?

Schema coverage is 100%, but the description adds meaningful context beyond the schema. It explains that apiUrl is required for registering a new environment (though not in schema's required list), and that studioUrl is optional for token-creation links. This clarifies parameter roles beyond basic descriptions.

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: 'Register (or rotate) a user-created Prisme.ai API token for an environment.' This is a specific action on a distinct resource, and no sibling tool performs token registration, making it easily distinguishable.

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 explicit guidance on when to use this tool vs. the alternative: it strongly recommends the out-of-band CLI, explains privacy risks, and states to only use this tool if the user explicitly chooses to paste the token. It also clarifies when to provide apiUrl and studioUrl for new environment registration.

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