transformatron

Overview Schema Source Related Servers Discussions Admin

run_transform

Execute a Maltego transform on one input entity to validate its output, returning run state, severity messages, entity and link counts, or full JSON when needed.

Instructions

Run a transform against one input entity and return its results.

The output starts with the run state, then each status message prefixed with its severity ([INFO], [WARNING], [ERROR], [DEBUG]), then the entity count and the number of distinct (type, value) pairs, one line per entity: type value {property=value, ...} [link label], and the link count. A run that FAILED also shows the last Python traceback from the server log.

Check the entity count and the message severities: a transform can report success while producing nothing, and an upstream 403 or 500 logged as [ERROR] still ends the run in a success state; a run like that with no entities gets a Warning line under the state. An unknown transform id comes back with how to find the right one. See docs/transform-authoring.md.

Args: transform_id: Fully qualified transform name from list_transforms. entity_type: Maltego type of the input entity, e.g. maltego.Domain. entity_value: Value carried by the input entity. settings: Optional transform settings, keyed by setting name. timeout: Seconds to wait before cancelling the run. full: Return every entity and link as the full JSON the server sent instead of one line each. Use it when a property, display field, or overlay that the summary cuts short matters.

Input Schema

Name	Required	Description	Default
`full`	No
`timeout`	No
`settings`	No
`entity_type`	Yes
`entity_value`	Yes
`transform_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 17, 2026

addedInput schema / properties / full

Added value: +{
+  "default": false,
+  "title": "Full",
+  "type": "boolean"
+}

First observedv0.1.0Aug 14, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so unusually well: it warns that a transform can report success while producing nothing, that an upstream 403/500 logged as [ERROR] still ends the run in a success state, that such runs get a Warning line under the state, that FAILED runs include the last Python traceback, and that an unknown transform id returns remediation guidance. These are non-obvious runtime behaviors an agent could not infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose sentence, then organized into output format, operational warnings, and an Args block — well structured with no filler prose. The multi-paragraph output-format walkthrough is heavier than strictly needed given an output schema exists, which is the only inefficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter tool with zero annotation coverage, the description covers everything an agent needs: all argument semantics, the exact output layout, failure-mode interpretation, and where to look for the transform id. Nothing material to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it documents all six parameters with meaning beyond their titles: transform_id must be fully qualified and comes from list_transforms, entity_type is a Maltego type with an example, entity_value is the carried value, settings are keyed by setting name, timeout is seconds before cancellation, and full returns raw server JSON with a stated rationale.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'Run a transform against one input entity and return its results.' An agent can distinguish it from list_transforms/get_transform/scaffold_transform purely from the name plus this sentence, since those retrieve or create while this executes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a workflow pointer ('Fully qualified transform name from list_transforms') and explicit guidance for one parameter ('Use it when a property, display field, or overlay that the summary cuts short matters'), which is real when-to-use advice. However it never states when NOT to invoke it or names an alternative execution path, so the tool-selection guidance remains implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server