register_feature

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

With no annotations, the description carries the burden of disclosing behavior. It transparently states that steps are ordered and that the AI will use this order to understand flows, and informs about overwrite semantics. It does not mention side effects like validation or persistence, but the 'Define or update' phrasing implies mutation, and the overwrite guidance adds practical behavior. No contradictions.

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

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

The description is three sentences, front-loaded with the action, and every sentence earn its place: defining the resource, explaining the key structure, and providing the critical overwrite guidance. No filler or redundant information.

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

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

The tool is complex (nested workflow array, optional test_scenarios, overwrite logic), but the description covers the core usage and ordering behavior. The schema provides extensive parameter docs, and the description highlights the AI's use of order. It could mention that project names must be pre-registered, but this is in the schema's project description. Overall, adequate for the complexity level.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the workflow parameter's semantics ('Each step maps what happens in mobile, backend, and admin') and the overwrite parameter's purpose ('Use overwrite=true to replace an existing feature'). This goes slightly beyond the schema, but doesn't cover all parameters like test_scenarios, though those are well-documented in the schema.

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

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

The description clearly states the verb 'Define or update' with resource 'a feature with its multi-project workflow steps', immediately distinguishing it from sibling tools like remove_feature and get_feature. It also specifies the key structure (steps mapped to mobile/backend/admin), making the tool's purpose unambiguous.

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

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

The description explains that the tool can both create and update features, and explicitly mentions the overwrite=true flag for replacing existing features. It does not mention when to prefer this over other tools, but the purpose is clear enough that usage context is implied. Lacks explicit exclusions or alternatives.

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