QA: Describing RPC methods for LLMs

This document explains how to describe RPC methods and parameters so that LLMs (and other MCP clients) can correctly understand and fill tool arguments.

1. Use typed parameters instead of raw array

  • Prefer a ValuesObject (or DTO) with JsonProperty for object parameters so the tool schema shows exact property names and types.
  • For lists of primitives use int[], string[], float[], or bool[] in params_types so the schema shows array with the correct items type (e.g. list of IDs as int[]).
  • For lists of objects use a typed array in params_types (e.g. CommitValuesObject[]) so the schema includes an items object with the right shape. Reflection only sees array, so set params_types in the database (e.g. in a migration) for any of these typed-array parameters; see below.

2. Set rpc_methods in the database for complex params

  • description: Set a short, clear description. It is shown in tools/list and helps the LLM choose and call the tool. You can mention required vs optional at the top level (e.g. “Params: commits (array of commit objects), serviceName, idProject. Per commit: required — remote_id, message, commit_datetime, project_name; optional — stat_additions, stat_deletions.”).
  • params: Human-readable param list (e.g. ["CommitValuesObject[] $commits","string $serviceName","int $idProject"]). Used for display and parameter name resolution.
  • params_types: JSON array of PHP types (e.g. ["plugin\\Commits\\domain\\model\\CommitValuesObject[]","string","int"]). This drives RPC deserialization and MCP JSON Schema generation. For array-of-object params you must set this in a migration; syncRpcMethods fills it from reflection and only sees array.

Example migration:

INSERT INTO rpc_methods (plugin, method, rpc_method, params, description, sections, return_type, params_types)
VALUES (
    'Commits',
    'batchCreateByProjectID',
    'batchCreateByProjectID',
    '["CommitValuesObject[] $commits","string $serviceName","int $idProject"]',
    'Batch creates service commits for a project. Params: commits (array of commit objects), serviceName, idProject. Each commit: required — remote_id, message, commit_datetime, project_name; optional — stat_additions, stat_deletions (default 0).',
    '[]',
    'array',
    '["plugin\\\\Commits\\\\domain\\\\model\\\\CommitValuesObject[]","string","int"]'
);

3. Use JsonProperty on the VO for schema and deserialization

  • Put #[JsonProperty("key_name", true)] on setters for required fields and #[JsonProperty("key_name")] for optional ones. The JSON key (e.g. remote_id, project_name) must match what the client sends.
  • Only properties with JsonProperty are included in the MCP schema and in RPC request deserialization. Use the same VO for both the RPC parameter type and the schema.

4. Keep names and types consistent

  • Parameter names in params (e.g. commits, serviceName, idProject) are the names the client sends in arguments. The schema is built from params_types and the VO classes, so the tool definition stays in sync with what the server expects.