Create code tour card

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: file ordering (explicit files keep order with README/manifests hoisted, archives use a specific order), the packing behavior (parts of ~32,000 rendered characters regardless of file count, so even a handful of medium files splits), and the pagination protocol (parts.current/total/hasMore, with explicit instructions to call again with part: current+1). It also discloses that matching is case-sensitive and terms are plain text. This is rich, actionable behavioral context.

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 fairly long but packs in essential behavior. It front-loads the main purpose and the ordering/participation logic. However, some redundancy exists: the part parameter is described both in the description and in the schema, and the tutorTerms matching rules are detailed but necessary. It could be tightened, but no sentence is wasted; the length is justified by the complexity.

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 complexity of this tool (11 parameters, multiple modes, pagination, tutor term matching), the description is remarkably complete. It covers the main behavioral quirks (splitting, ordering, case-sensitivity, machine distinction), and the output schema exists to document the return values. The description plus schema cover everything an agent needs to call this tool correctly, including the pagination loop.

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 description coverage is 73%, so the schema already documents many parameters. The description adds value for ambiguous or under-documented parameters: it explains the packing behavior for parts, the ordering logic, the archivePath machine caveat, and the tutorTerms matching rules (case-sensitive, longest first, not in code samples). It doesn't cover every param (e.g., maxTabs, contextActions aren't described), but the description's comments on key parameters like part, archivePath, and tutorTerms go beyond 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 tool renders a project's source as an interactive card with one tab per file, including copy buttons. It distinguishes itself from sibling card-creation tools (create_chart_card, create_tab_card, etc.) by focusing on source code rendering and specifically mentions the code-related features.

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 alternatives: it explains the two modes (passing a zip archive vs passing files explicitly), notes the machine-location caveat for archivePath over a remote bridge, and mentions the alternative of passing files when the archive exists only on the caller's side. It also addresses the pagination workflow implicitly.

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