ditrixnew EDT-MCP — tool contract (consistency)
The same concept must behave the same way across every tool. This skill is the canon to hold to.
Parameter naming
| Concept | Canonical | Anti-example |
|---|---|---|
| Project | projectName |
project |
| Module | modulePath (from src/; the resolver also accepts an absolute path) |
module, or a decomposed objectName+moduleType+formName+commandName |
| Fully-qualified name | fqn |
— |
| Object name | objectName |
— |
| Synonym / language | synonym / language |
— |
| Limit / offset | limit / offset |
maxResults, maxDepth |
Parameter names are lowerCamelCase — ToolContractConsistencyTest fails snake_case. When renaming a parameter, accept the old name as a documented alias for one release, then deprecate.
Read parameters typed
Read arguments via JsonUtils.extractStringArgument/extractIntArgument/extractBooleanArgument/extractObjectArray; check required ones via JsonUtils.requireArguments(params, "a", "b") (returns a ready error-JSON or null). Don't parse a raw Map<String,String> by hand. (There is no typed ToolParams class — JsonUtils is the canon.)
Every parameter read in execute() must be declared in getInputSchema() (otherwise it is invisible to schema-driven clients) and vice versa.
Error contract
- Errors only via
ToolResult.error(...)(machine-readable: success=false + message/code). Never return a bare"Error: …"/"Project not found"string, never let an exception escape the tool. - "project not found" — one text/shape through the shared
ProjectContextresolver.
Output format
- Similar tools use the same format (don't make one JSON and another markdown without a reason). The plugin default is markdown (see
IMcpTool.ResponseType). - JSON fields use one style (don't mix camelCase/snake_case in similar responses).
- not-found — one semantics: an empty list for "list", an error for "get a specific one". Don't mix null/empty/error.
Response format policy (Markdown vs JSON)
structuredContent/JSON is for the client to consume (UI rendering, verbatim round-trip of identifiers, a future outputSchema), NOT for the agent to read. MARKDOWN is the default (token-efficient, readable).
A tool returns JSON only when its result carries:
- (a) round-trip IDs another tool consumes;
- (b) machine-structured positions (e.g. error line/column);
- (c) a declared
outputSchema; - (d) UI-rendered data.
Action/confirmation/status results with none of these return MARKDOWN. write_module_source is the reference MARKDOWN action tool; AbstractMetadataWriteTool subclasses stay JSON because they return the created object's round-trip FQN.
Tool families that stay JSON, and why:
- metadata-writes (
create_metadata,modify_metadata,delete_metadata) → addressed by FQN (a); - debug / profiling tools → launch / application / breakpoint IDs + live session state (a);
validate_query→ error line/col (b);list_configurations→ config identities (a);clean_project,update_database→ destructive status whose JSON shape is consumed by e2e (d-like).
Markdown action tools (revalidate_objects, export_configuration_to_xml, import_configuration_from_xml, write_module_source) emit status + paths/counts only — no round-trip data. Build the body with FrontMatter + a markdown summary; any table goes through MarkdownUtils (escapes every cell); errors still via ToolResult.error(...).
Pagination
Use the shared Pagination (utils/Pagination.java: one limit/offset, one truncation-notice format). Don't invent a per-tool scheme.
Result / markdown assembly
Through ToolResult/JsonUtils and the shared markdown-table builder, not a hand-rolled StringBuilder.
Schema ↔ code ↔ README
BuiltInToolRegistraris the source of truth for the tool set; the README catalog + the e2e golden (tests/e2e/tools_list.golden.json) must match it. A new tool changes the golden → regenerate (EDT_MCP_UPDATE_GOLDEN=1).- Every tool: a non-empty meaningful description and a description for every parameter.
Class placement
tools/impl/ holds IMcpTool classes only. Utilities/abstract bases go in utils//tools/base/. Project/model resolution goes through the shared helpers (skill edt-mcp-architecture). ru/en correctness — skill edt-mcp-bilingual.