fpt_launch_app

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

With no annotations provided, the description carries the full burden — and it delivers: it discloses the degraded fallback path ('falls back to a direct open -a launch and surfaces a warning'), side effects ('can CREATE a missing Flame project'), the 'already running' single-instance refusal with its force override, and three fully documented failure modes with root causes and remediation steps. It even discloses an architectural limitation ('The tool cannot do this because it cannot deliver the browser approval step'). The Chat 93/98 references indicate provenance and that the FLAME write path was deliberately removed, preempting confusion about missing functionality. No contradictions with annotations exist since none are present.

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 structure is excellent: front-loaded purpose, then clearly delineated sections (OS-first, version selection, MAYA/Sequence, FLAME, refusal, failure modes) using a scannable headerless markdown format. Every section earns its place for a tool of this complexity, and the failure-mode catalog is dense with load-bearing knowledge rather than fluff. However, inline references like 'Chat 93' and 'Chat 98' are historical noise for a fresh agent, and the step-parameter explanation appears in both the description and the schema, creating slight redundancy. It could shed 10% of its bulk (especially the Chat references) without loss.

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 10-parameter, multi-DCC tool with three routing modes and an interactive discovery protocol, this description is exceptionally complete: purpose, scope, routing fallbacks, precedence rules, per-DCC behavior, interaction loop, overrides, explicit failure taxonomy, and user-facing remediation — everything is present. An agent facing an auth-expiry or bundle_cache_fallback_roots error would be able to diagnose and communicate the issue without ever seeing the real failure. With an output schema present, the absence of return-value details is correct, not a gap.

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?

Despite 0% schema coverage, the description deeply enriches the highest-complexity parameters: step ('a bare Sequence launch is step-LESS... resolves it to its Step Task'), route ('for flame this runs pre-launch hooks and can CREATE a missing Flame project'), and flame_project (link discovery and the 1:1/INCONSISTENT/none semantics). Parameters like dry_run, workspace, and force are left entirely to the schema's own detailed descriptions, which is acceptable for the low-ambiguity ones but slightly asymmetric with the depth given to others. The description focuses its limited compensation budget exactly where parameter semantics are non-obvious.

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 opening sentence — 'Launch a DCC application scoped to a ShotGrid entity' — provides a specific verb (launch), a specific resource type (DCC application), and a clear scope (ShotGrid entity), which cleanly distinguishes it from the querying/uploading/publish siblings in its list. The 'scoped to a ShotGrid entity' phrasing conveys the same scope-narrowing quality as the get_calls HIGH example's 'in date range' qualifier. Purpose is instantly graspable with no ambiguity.

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?

Massively explicit: describes the internal route selection ('auto' prefers toolkit; 'direct' skips it; 'toolkit' forces pre-launch hooks), the choice_required protocol ('ask the user and re-call with flame_project=<choice>'), and the precedence rule ('FPT-selected version... is authoritative over newest installed'). The list_projects schema description adds 'Use after list_projects/choice_required' and the critical exclusion 'never guess: a name-derived match is NOT evidence of a native FPT link'. The FLAME decision tree (one link → open directly; several → INCONSISTENT; none → choice_required) functions as explicit when/when-not guidance.

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