edt-mcp-tool-conventions

name	edt-mcp-tool-conventions
description	Cross-tool consistency contract for EDT-MCP tools — parameter naming, error shape, output format, pagination, not-found semantics, schema/README alignment. Use when editing any class under tools/impl, adding a parameter, changing a tool's output, or reviewing a tool for consistency.

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 ProjectContext resolver.

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

• BuiltInToolRegistrar is 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.