ButtonHeist MCP exhibits severe definition quality gaps across all six tools. While tool registration is visible in ToolDefinitions.swift and tool annotations are present, the actual tool descriptions and parameter documentation are critically absent from the evaluable source code. The codebase shows that descriptions are sourced from FenceCommandDescriptor objects (descriptor.description) and schemas from inputJSONSchema, but these descriptor definitions are not included in the provided source. Per the hard rules, tools without visible descriptions score 0 on description, and tools without visible input schema details cannot exceed 30 on schema. Tool naming follows weak conventions: 'perform' is generic and vague; 'run_heist' and 'describe_heist' compound two concerns unnecessarily. Parameter names lack descriptive suffixes (e.g., 'target' should be 'target_name' or 'target_id'). No parameter descriptions are visible in the schema definitions. No output schemas are documented. Error handling is absent from all tool definitions.

• Create a documented FenceCommandDescriptor definition file (or extend existing) with complete descriptions for each command. Each description should answer: What does this tool do? When should the LLM use it? What does it return? Target 50 - 200 characters per pattern baseline.
• Add parameter descriptions to every input parameter. For 'target' in connect, clarify 'Target heist name or ID to connect to'. For 'step' in perform, explain the expected DSL format. For 'lint' in validate_heist, specify valid lint profile names and their meanings.
• Document output schemas for every tool. Specify the structure of successful responses (fields, types, cardinality) and error responses. This enables LLMs to plan downstream calls and extract data correctly.
• Rename vague tools: 'perform' → 'execute_heist_step'; 'connect' → 'connect_to_target'; 'describe_heist' → 'get_heist_details'. Use verb_noun naming to clarify intent.
• Expand parameter naming: 'target' → 'target_name'; 'detail' → 'include_details' (boolean) or 'detail_level' (enum: basic, full); 'lint' → 'lint_profile' with enum constraint (e.g., strict_test, standard).
• Add error handling guidance. Define which errors are retryable (e.g., 'Target temporarily unavailable. Retry in 5 seconds.') vs user-fixable ('Invalid lint_profile. Valid values: strict_test, standard, lenient') vs fatal.
• Add pagination to list_heists with 'limit' (default 20, max 100) and 'offset' parameters. Return 'total_count' and 'items' array in response. Clarify in description: 'Returns paginated list of available heists. Use offset/limit for large datasets.'