getCodeExample

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

With no annotations, the description carries the full disclosure burden. It clearly states what the tool returns ('full Kotlin + Swift code, an explanation, gotchas, and the SDK features it exercises') and clarifies a key potential misperception about byok_anthropic (not related to the assistant runtime). It does not cover rate limits or auth, but this is a reference retrieval tool with no mutation, so the transparency level is strong.

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 long, but the tool exposes 13 distinct patterns that each require explanation. The opening sentence is clear and purposeful, and the bulk organizes usage recommendations by bolded alternatives. While it could benefit from a bullet list, the density is justified and front-loaded with the most important direction ('start with assistant_agent_loop').

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?

Despite having no output schema, the description discloses return contents and maps every pattern to its intended use context. It even explains that the pattern affects the example's code shape and verification approach, and covers when not to use the tool. The description is effectively a complete usage guide for the tool.

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 covers the single `pattern` parameter with an enum, the description provides deep semantics for nearly every enum value, explaining what each pattern is for, when to use it, and how it relates to others. This goes far beyond the schema's tiny one-line description, making the parameter choices much more meaningful.

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 'Reference library — retrieve a complete SDK code example (Kotlin + Swift) for a use case', providing a specific verb and resource. It immediately names recommended sibling patterns (assistant_agent_loop, agent_driven_e2e_full_loop) and distinguishes them from fine-grained alternatives, clearly differentiating this tool from siblings.

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?

Explicit guidance is given: 'USE when you're about to write handler code...' and 'DON'T USE for capability discovery (use getPlatformInfo) or per-feature minimal usage (use getCapabilityGuide)'. It also explains when to choose each pattern relative to alternatives (e.g., 'For the dedicated agent-side test workflow... agent_driven_e2e_full_loop').

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