The server defines 18 tools with explicit schemas using Zod validators, descriptions, and consistent error handling. However, critical gaps exist: (1) Parameter descriptions are minimal or absent for many tools, most parameters lack guidance on constraints, formats, or dependencies. (2) Output schemas are not formally documented; tools return JSON stringified objects without declared field contracts, forcing LLMs to parse unstructured text. (3) Tool descriptions are brief (10-30 chars on average) and lack WHEN/WHY context, dependency hints, or recovery guidance. (4) Destructive tool (delete-issue-relation) lacks confirmation or dry-run safeguards. (5) No pagination or result-limit documentation for list tools. (6) Parameter naming is mostly clear (verb_noun convention followed) but lacks type suffixes (e.g., 'id' instead of 'initiative_id') when IDs appear in multiple tools. The Zod schemas ARE present in code and properly typed, which prevents a lower score, but the absence of parameter descriptions and output schema documentation is a significant deviation from production baselines (100% of A+ tools document params and output).
Parameter descriptions are minimal or missing. Most input parameters lack explanations of constraints, valid formats, or dependencies. The rubric requires descriptions for every parameter; LLMs cannot infer parameter meaning from names alone.
Output schemas are not documented. Tools return JSON.stringify(object) with no declared field contract. LLMs cannot plan downstream calls or extract the right data when they don't know what fields to expect. Baseline: 100% of A+ tools document return types.
Add 50-200 character descriptions to every tool. Follow the pattern: 'WHAT does it do? WHEN should the LLM call it instead of similar tools? What does it return?' Example: 'View a Linear project by ID. Call this before update-project to verify the project exists and see its current state. Returns project metadata including name, description, state, and priority.'
Document every input parameter with a 1-sentence description explaining what it controls, valid format, and constraints. Example for 'priority': 'Issue priority (0=none, 1=urgent, 2=high, 3=medium, 4=low). Determines sort order and urgency signals in the UI.'
Add formal output schemas to tool documentation. Example for view-project: 'Returns {id, name, description, state, priority, createdAt, updatedAt}'. This enables LLMs to plan chains (e.g., knowing that view-project returns 'name' so they can pass it to search_projects).
Implement pagination for list-initiatives, list-projects, and search-issues. Add parameters 'limit' (default 20, max 100) and 'offset' (default 0). Return {items: [...], total: N, hasMore: boolean}. Capping results at 20-50 prevents context-window exhaustion.
For delete-issue-relation, add a 'confirm' boolean parameter (default false). When false, return a summary of what would be deleted. When true, perform the deletion. This prevents accidental data loss from agent mistakes.
Enrich error messages with recovery hints. Instead of 'Linear API Error: Project not found', return 'Project <id> not found. Available projects: [list]. Call list-projects to see all project IDs.'
Tool descriptions are too brief (10-35 chars on average vs. baseline 194 chars p50). They lack WHEN/WHY context, dependencies, and recovery guidance. LLMs rely on descriptions to decide whether to call a tool, sparse descriptions lead to wrong tool selection. Example: 'View a Linear project by ID' doesn't explain if this is for inspection or as a prerequisite for update.
Destructive tool delete-issue-relation lacks confirmation or dry-run safeguard. Agents make mistakes, irreversible operations should support a confirm step to prevent catastrophic errors.
List tools (list-initiatives, list-projects, search-issues) do not document pagination, result limits, or offset/limit parameters. Without pagination, large result sets blow the context window. Baseline: tools returning lists should accept page/offset and limit and return total count.
Parameter names lack type suffixes. Multiple tools accept 'id' parameters (projectId, initiativeId, relationId) but do not suffix them with the resource type in all cases. Inconsistency ('projectId' vs 'id') forces LLMs to reason about field mappings, increasing errors.
Error handling returns LinearError messages without recovery guidance. Error responses should tell the LLM what to do next. A bare 'Linear API Error: <msg>' gives the agent nothing actionable.
Standardize parameter naming. Use suffixes consistently: 'project_id', 'initiative_id', 'issue_id', 'relation_id' (or camelCase projectId, initiativeId, issueId, relationId). Apply uniformly across all tools so tool chaining is obvious to LLMs.
Add tool annotations (if SDK supports). Mark read-only tools with readOnlyHint:true, destructive tools (delete-issue-relation) with destructiveHint:true. This helps agents understand side-effect risk.
Document tool dependencies in descriptions. Example: 'If you only have a project name, call list-projects first to get the ID, then pass it to this tool.'
Validate and constrain the 'state' enum early in handlers. Return 'Invalid state: got "pending", must be one of: planned, started, paused, completed, canceled' instead of a generic API error. This lets the LLM self-correct.