generate_code

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: generated code includes token issuance, request/response handling, websocket subscription, and a confirm=True safety guard so orders/exchanges are not sent prematurely. It stops short of describing error behavior or code usability caveats.

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 concise sentences, all front-loaded: main purpose, then REST/real-time variants, then safety behavior and the token exception. Every sentence earns its place with no filler or redundant expansion.

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 one-parameter generator with a rich output schema and safety annotations, the description covers the core input semantics and all generation modes. It is slightly incomplete about when to consult api_conventions and what happens on invalid api_type values, but nothing essential to calling it correctly is missing.

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%, and the parameter description already explains that api_type must come from search_api/get_api_detail and that 'token' produces token-issuance code only. The tool description repeats the token special case but adds little semantic value beyond the schema, so the baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Creates Python code that calls api_type' and then disambiguates REST, real-time websocket, and token-only generation modes. This makes the purpose unmistakable and clearly distinguishes it from the sibling discovery/inspection tools.

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 implies usage by API type and special-cases api_type='token', while the parameter schema tells agents to use a value from search_api or get_api_detail. However, it never explicitly states when to prefer this tool over api_conventions or other siblings, nor does it give exclusions. Guidance is adequate but mostly left to inference.

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