Table of Contents

TTMSMCPTool Class

A single callable tool published by a server: its name and description, the input parameters it accepts, the behavioural hints and schemas advertised to the client, and the callback that runs when the client invokes it.

API unit family: TMS.MCP.Tools Inherits from: TTMSMCPBase

Syntax

TTMSMCPTool = class(TTMSMCPBase)

Remarks

A tool is executed through one of three mutually exclusive callback shapes. The positional shape (the method property or the execute event) receives the arguments as an array in parameter declaration order. The name-keyed shape (the dynamic method property or the dynamic execute event) receives them in a dictionary keyed by parameter name, which is the shape to choose when optional parameters may be absent. The structured shape (the structured method property) also receives them by name but returns a ready-made JSON object matching the declared output schema. When a name-keyed callback is assigned it takes precedence over the positional one; the structured callback is only reached through the dedicated structured execution method.

Properties

Name Description
DestructiveHint When True, warns the client that the tool may change or remove existing data in a way that cannot be undone, so it should confirm with the user before invoking it. It only carries meaning for a tool that is not read-only. Published as destructiveHint only when set.
DynamicMethod Anonymous method run when the tool is invoked, receiving its arguments keyed by parameter name. Assigning it switches the tool to the name-keyed execution path, which is the shape to choose when optional parameters may be absent from a call.
IconsJSON JSON array of icon descriptors published as the icons of the tool, so a client can show the tool with an image. It is only published when the string parses as a JSON array; the builder's add-icon step is the convenient way to accumulate entries.
IdempotentHint When True, tells the client that repeating the call with the same arguments has no further effect beyond the first call, so it is safe to retry after a timeout or an unclear failure. Published as idempotentHint only when set.
Method Anonymous method run when the tool is invoked, receiving its arguments by position. It takes precedence over the execute event, and is itself bypassed when a name-keyed callback is assigned.
OpenWorldHint When True, tells the client that the tool reaches out to an open, external world such as the internet or a third-party service, so its result may differ between two identical calls and cannot be predicted from the arguments alone. Leave it False for a tool that works on a closed, local set of data. Published as openWorldHint only when set.
OutputSchema JSON Schema describing the structured result of the tool, published as outputSchema when not empty. Pair it with the structured callback so the returned JSON object actually matches the schema that was advertised.
Properties Input parameters the tool accepts. They define the published input schema and, for a positional callback, the order in which the arguments arrive.
ReadOnlyHint When True, tells the client that the tool only reads and never changes anything in its environment, so it can be run without asking the user for permission first. Leave it False for any tool that writes. Published as readOnlyHint only when set.
ReturnType Declared type of the value a positional or name-keyed callback returns. It selects how that value is converted to JSON before it is sent back. Defaults to ptString, and is not used by the structured callback, which returns JSON already.
StructuredMethod Anonymous method that receives the arguments by name and returns a JSON object matching the declared output schema. It is only reached through the structured execution method, so it does not interfere with the positional or name-keyed callbacks.
TaskSupport Declares whether the client may, or must, invoke the tool as a long-running task. Anything other than tsForbidden publishes an execution object carrying the capability. The setting is an advertisement only: it does not by itself make the callback run asynchronously. Defaults to tsForbidden.
Title Short human-readable label published in the tool's annotations and shown by a client in place of the raw tool name. Omitted when empty.

Methods

Name Description
CreateBuilder Starts the fluent configuration of a new tool.
Execute Runs the tool through its positional callback. The method property is used when assigned, otherwise the execute event.
ExecuteMethod Runs the tool for an incoming call and converts its result to JSON. Required parameters are validated and every supplied parameter is converted to the declared type before the callback runs; string values are coerced to a number or a Boolean where the parameter declares one. The name-keyed callback is used when one is assigned, otherwise the positional one, and the returned value is converted using the tool's return type.
ExecuteStructured Runs the tool through its structured callback, which receives the arguments by name and returns a JSON object directly instead of a value that still has to be converted. Use it when the result must match a declared output schema.
ToJSON Builds the descriptor the server publishes for this tool when a client lists the available tools. The descriptor carries the name and description, an annotations object when a title or at least one hint is set, the input schema, and the optional outputSchema, icons and execution members when those are configured.

Events

Name Description
OnDynamicExecute Occurs when the tool is invoked and no name-keyed method is assigned, receiving the arguments keyed by parameter name. Assigning it switches the tool to the name-keyed execution path.
OnExecute Occurs when the tool is invoked and no positional method is assigned, receiving the arguments by position. Use it to implement a tool on a component or form at design time.
OnGenerateInputSchema Occurs while the tool serializes itself, giving the handler the chance to supply a hand-written input schema. When the handler returns a non-empty string, that JSON replaces the schema derived from the tool's parameters; when it returns an empty string, the generated schema is kept.

Used by