Create Sub Job

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

It discloses important behavior beyond annotations: HTTP 201 success with payload, non-idempotency ('calling it again creates another record'), and error payload statuses for 401 (expired token), 403 (missing permission), and 404 (unresolved id). This gives the agent clear expectations for auth and failure handling.

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?

Every sentence earns its place: purpose, side effect, error behavior, required params, API area, and endpoint. Information is front-loaded and no filler is present.

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 two-parameter POST tool with no output schema, this description covers all essentials: what it does, return value, non-idempotency, failure modes, required inputs, and endpoint. Nothing critical is missing for an agent to invoke it correctly.

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% with descriptions for both project_id and sub_job, so the baseline is 3. The description merely restates 'Required parameters: project_id, sub_job' without adding semantic detail about the sub_job structure or constraints beyond what the schema already provides.

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 'Create a new Sub Job,' matching the tool name with a specific verb and resource. It immediately states the result (returns the new id with HTTP 201) and explicitly notes that calling it again creates another record, distinguishing it from update or delete operations.

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 gives clear context: this is for creating a sub job, requires project_id and sub_job, and warns about duplicate creation. However, it does not name alternative tools like sync_sub_jobs or update_sub_job, so it misses explicit when-to-use/exclusion guidance.

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