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 https //docs swimlane com/how hero ai executes components , https //docs swimlane com/components#hero ai visibility options , https //docs swimlane com/ai agents in orchestration for hero ai native action playbook prompts (failure paths, tool limits, non deterministic output), see https //docs swimlane com/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 https //platform claude com/docs/en/agents and tools/tool use/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 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