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

Annotations already flag readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds rich context: for s3 it notes the 5000-object listing limit and warns to relay the `warnings` array and suggest an S3 lifecycle rule; for dedupe it details what happens when the same file reappears; for run-now it explains status transitions to success/failed/no-files. It also warns that preRules/postRules compile server-side (never pass raw code). Minor deduction: some behaviors (e.g., what happens on delete) are not enumerated, but the description goes well beyond the structured annotations.

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 substantial but every section serves a purpose: lead verbs, per-type paragraphs, an 'IMPORTANT' callout for the most common mistake, a bulleted list of trigger types, and a final 'after firing' note. Formatting with newlines and bold text improves scannability without bloat.

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 19-parameter, 7-action, 4-type tool, the description covers all operational contexts: create vs. update vs. run-history, prerequisites (connection tested, spec analyzed, table-source spec for spec_success/schedule), type-specific requirements (s3Bucket for aws_s3), and monitoring via run-history. The output schema's existence lowers the need to document return values, and the description still mentions `filesPulled`/`message` fields. Nothing critical left unexplained given the tool's complexity.

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 already 100%, so the baseline is 3. But the description goes further: it explains the `dedupe` parameter's real-world consequences (silently skipped re-uploads or reloaded files), documents connection prerequisites, clarifies the relationship between type and connection, and explains the `warnings` array in the response, adding meaning beyond the schema's prose.

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 ('Create, list, update, delete, or fire') and resource ('a workspace job trigger') and immediately distinguishes four trigger types (sftp/aws_s3, spec_success, schedule) with concrete examples ('run this after the customers load finishes'). This clearly differentiates from siblings like setup_scheduled_pull and manage_connection by naming them where relevant.

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 throughout: 'prefer setup_scheduled_pull' for first-time scheduled pulls, 'Prefer spec_success when... prefer schedule when... ask if genuinely ambiguous,' and the special constraint that spec_success/schedule only target table-source specs. This goes beyond vague alternatives to provide decision rules with concrete user-phrasing examples.

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