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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It goes beyond a simple 'store' by disclosing that credentials are verified live against the venue, sealed at rest, and that the material is never returned. It also states that authentication is required. This is comprehensive for a credential storage tool.

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 (three sentences) and front-loaded with the core purpose. Every sentence adds value: the first defines the action and key safety properties, the second details the accepted credential shapes, and the third states the authentication requirement. No fluff or redundant 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 (9 parameters, two mutually exclusive shapes, no output schema), the description covers the essential aspects: what it stores, supported shapes, safety guarantees (never returns material), and auth. It does not explicitly state what the tool returns (e.g., a confirmation or label), but 'material never returned' partially mitigates that. The optional parameters (label, signature_type) are documented in the schema, so the description is complete enough for an agent to invoke the tool correctly.

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?

Although the schema has 100% description coverage for individual parameters, the description adds crucial grouping by presenting two distinct shapes (signer_private_key + maker, or api_key + secret + passphrase + maker + signer). This semantic relationship is not evident from the schema alone and helps the agent choose the correct parameter set. It does not explain optional parameters like label or signature_type, but those are self-explanatory in the schema.

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 action ('Store a prediction-market venue credential'), the exact resource (credential for prediction-market venues), and distinguishes it from sibling tools like list_pm_credentials and revoke_pm_credential. It also specifies supported venues (Polymarket) and credential shapes, leaving no ambiguity about what the tool does.

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?

It provides clear context for when to use the tool (storing a credential) and specifies the accepted input shapes (either signer_private_key + maker or api_key + secret + passphrase + maker + signer). It does not explicitly contrast with alternatives, but the purpose is clear enough that an agent would infer the correct usage. 'Auth required' adds a prerequisite.

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