AI-Friendly Component Best Practices

Use this guidance when you create, configure, and document components so Hero AI and AI SOC can select them reliably, map inputs correctly, and interpret outputs.

At a Glance

If you need to…	Focus on…
Help Hero AI pick the right tool	Clear single purpose, name, and description
Improve mapping and run quality	Well-defined inputs and outputs, required fields, and flat schemas
Help the model decide what to do next	Explicit result messaging and clear errors
Support AI SOC plans and dynamic mapping	AI SOC specifics

See also: How Hero AI Executes ComponentsHow Hero AI Executes Components, ComponentsComponents (Hero AI visibility), Create and Modify Components with Hero AICreate and Modify Components with Hero AI, AI Agents in OrchestrationAI Agents in Orchestration. For Hero AI native action playbook prompts (failure paths, tool limits, non-deterministic output), see Hero AI Native Action.

Clear Single Purpose

The component should do one thing that is easy to describe. That one thing can still be complex (for example, quarantine an endpoint on the network), but it must be a single, understandable outcome.

Do not build components that do two or more separate jobs. Split separate tasks into separate components.

Clear Descriptive Name

The name should state what the component does. Avoid vague titles. If the component targets a specific product (for example, creating a firewall rule in Check Point), include that in the name, such as Add Check Point firewall rule.

Clear Description

Write a short, precise description of behavior and scope. For inspiration on how to describe a tool the model will call, see Implement tool use (Anthropic documentation).

Well-Defined Interface

Principle: Higher-quality input metadata and structure generally produce better mapping, execution, and downstream reasoning.

Field Names and Descriptions

Use specific names and descriptions on inputs and outputs. Prefer User ID over a generic ID.

For enumerated values or formats, document them in the field description. Be explicit about allowed values.

Avoid	Prefer
The Status field may have values such as New, In Progress, Blocked, Closed.	The Status field has one of the following values: New, In Progress, Blocked, Closed.

Required and Sensitive Fields

Use the Required input setting deliberately. Hero AI works to ensure required fields are populated at design time and runtime where possible.

Mark inputs sensitive when appropriate based on what the component does and what data maps into it.

Schema Shape

Prefer explicit types (string, number, boolean, and so on) over large, loosely defined objects.

Prefer a flat input and output structure. Avoid deep object nesting when you can.

For parameters that allow multiple or ambiguous formats (date-time strings, alphanumeric IDs), document the expected format in the field or component description.

Example of a documented timestamp field:

"timestamp": {
  "type": "string",
  "format": "date-time",
  "description": "ISO 8601 timestamp"
}

For free-form text inputs, add examples or short instructions for how the field should be used.

For query or filter parameters, prefer objects with defined fields. If you use strings, document how to build the query or filter, with examples.

Outputs

Include only outputs callers need. Remove parameters that add noise without purpose.

AI-Friendly Message Output

Optional but useful: write a clear message (or similar string) in the component output so the model can interpret run outcome and support next-step decisions. If structured outputs alone are ambiguous, a short human-readable line helps.

Error Handling and Retry Logic

For AI SOC, it is often better to fail the component than to return success when the task did not complete. For example, treat API credential failures as errors, not as handled exceptions that hide the problem.

You can influence follow-on behavior with explicit error text. In a Python script action, raise an exception with a clear message, for example:

Validate Error: input parameter 'days' cannot be negative

Exception: AWS SSO token has expired

AI SOC Considerations

AI SOC can select components from the investigation plan and map inputs dynamically from agent context. For the full AI SOC workflow (plans, verdicts, and case management), see AI SOC Solution.

Mechanism	What drives it
Selection	Component name and description only. Put anything that must influence selection into those fields.
Dynamic input mapping	Name, description, input field names, input field descriptions, and output field names. Complete these fields to support accurate mapping.

Common Interface Mistakes

Issue	Why it breaks down
Required input is an object without expanded sub-fields	The model and mapper cannot see what to supply
Required input is an array without expanded sub-fields	Same as above for list items
Input is optional but referenced by a downstream action	Runtime mapping gaps
Input is required but never referenced	Confusing requirements and failed validation
Wrong type (for example, string where boolean is needed)	Invalid values or silent coercion problems
Enum-only parameter with values not documented or declared	The model cannot know valid choices