linear_createInitiative

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

The description gives no behavioral transparency beyond the act of creation. It does not disclose side effects, required permissions, ownership implications, or what happens to connected projects. The annotations are all false and provide no safety hints, so the description carries the full burden of disclosure, and it fails to address any of it. There is no contradiction but also no meaningful information.

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 extremely short—one sentence that essentially paraphrases the tool name. While it is concise, it is under-specified and adds no value beyond the title. There is no front-loading of critical constraints or guidance. This is a case of under-specification rather than effective conciseness, as it fails to earn its limited word count.

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 complex tool with 8 parameters, an output schema, and many related sibling tools (getInitiatives, updateInitiative, archiveInitiative, etc.), the description provides almost no context. It does not explain what an initiative is in Linear, how it relates to projects or roadmaps, what the output looks like, or any typical usage patterns. The agent would be left without sufficient guidance to call this tool correctly in most scenarios.

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?

The input schema has 100% description coverage, with each parameter (name, icon, color, status, content, ownerId, targetDate, description) having a short explanatory description. Since the schema already documents the parameters, the description does not need to add details. However, the tool description doesn't provide any additional context about how parameters interact or which are essential beyond the required name field. This meets the baseline for high schema coverage.

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 states 'Create a new initiative' which clearly indicates the verb and resource. It is unambiguous and directly conveys what the tool does. However, it does not differentiate from other 'create' tools like linear_createProject or linear_createRoadmap, though the resource name itself provides some distinction. The description is a restatement of the tool's name with no added nuance.

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?

There is no guidance on when to use this tool versus alternatives. It neither explains under what circumstances an initiative should be created nor contrasts with related operations like updateInitiative or archiveInitiative. The description provides no context about prerequisites, workflow, or distinctions from sibling tools.

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