bt_add_run_eqs_service

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

With no annotations provided, the description carries the full burden, and it does substantial work: it discloses the mutation ('Attach or update'), the runtime trigger (while the parent branch is active), and the side effect (writes the selected result into a Blackboard key), plus the update_existing semantics. It stops short of stating whether the BT asset is persisted/saved or whether a recompile is required afterward, so it is strong but not exhaustive.

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 longer than minimal, but every section earns its place given 0% schema coverage: the lead states purpose and behavior, the Args block supplies necessary parameter semantics, and the KB pointer plus example anchor the usage. The structure front-loads purpose before details and avoids filler.

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?

For a mutation tool with 8 parameters, no annotations, and only 3 required fields, the description covers the essential ground: what it does, when it takes effect, what every parameter means, and a concrete example. An output schema exists, so return-value documentation is not its job. The only gaps are explicit failure modes and whether the asset modification is saved or compiled.

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 0%, and the Args block fully compensates by documenting every one of the 8 parameters with meaningful semantics: valid run_mode values are enumerated, parent_node_index's -1 sentinel is explained, and both booleans (update_bb_on_fail, update_existing) get a plain-language meaning. This adds exactly the value the raw schema lacks.

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 opening sentence names a specific verb and resource — 'Attach or update a built-in Run EQS service on a Behavior Tree node' — which clearly separates it from siblings like create_bt_service (which creates service assets) and eqs_add_test (which edits EQS queries). The behavioral follow-up (runs while the parent branch is active, writes the result into a Blackboard key) further pins down exactly what the tool does.

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 implies the right context — you use this when a BT branch should run an EQS query and store the result in a Blackboard key — but it never explicitly names alternatives or states when not to use it. An agent must infer the distinction from sibling names like create_bt_service, eqs_add_query, or add_bt_node rather than being told.

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