Behavior Trees

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond that: it discloses the return payload (converted text plus issues) and warns that conversion is lossy in both directions because some nodes have no equivalent. It does not describe failure behavior for malformed input, which keeps it below a 5.

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 core capability is front-loaded in the opening clause and the second sentence covers the return contract without padding. The nested parenthetical about ROS versions makes the first sentence dense and slightly harder to scan, but no sentence is wasted.

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 two-parameter, side-effect-free conversion tool with no output schema, the description covers input formats, target versions, return content, and lossy-conversion caveats. Combined with the exhaustive tree parameter documentation in the schema, an agent has everything needed to call it correctly.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the enum alone lacks by explaining what btcpp-v4 and btcpp-v3 correspond to in the ROS 2 ecosystem. It also reinforces that non-built-in node names must be declared in custom_nodes, a constraint that trips up naive callers.

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 states a specific verb and two concrete resources ("Convert between behavior3 JSON and BehaviorTree.CPP XML") plus the version targets, so an agent can immediately tell this is a format translator rather than a validator or node-lister. Referencing "the same way the editor imports and exports" pins down semantics no sibling offers.

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?

It gives clear selection context by mapping btcpp-v4 to ROS 2 Jazzy/Groot2 and btcpp-v3 to Humble, which is exactly the decision an agent faces when picking a target. It also routes to list_node_types for the built-in node list, but it never states when to prefer validate_tree or create_editor_link over this tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive) so the bar is lower, yet the description adds real behavior: the tree is encoded in the URL fragment, nothing is uploaded or stored, no account is required, and failures surface as validation errors. It stops short of describing URL size limits or what the failure payload looks like, which matters for a link-embedding tool.

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?

Three front-loaded sentences, each doing distinct work: what it returns, what it accepts in terms of privacy/side effects, and the failure mode. No filler or restatement of the title.

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?

Single required parameter, no output schema, and the description compensates by stating the return value is a URL and describing the failure case. Nothing an agent needs in order to call this correctly is missing.

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 coverage is 100% and the schema's tree description is already exhaustive (behavior3 JSON shape, custom_nodes declaration rules, project and XML alternatives). The description usefully frames the parameter's semantic consequence — the tree travels inside the link — rather than repeating schema detail, which is the right division of labor.

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?

Names a specific verb and resource ('Returns a url that opens the tree in the behaviortrees.com editor') and immediately characterizes the scope: auto-laid-out, editable, no account needed. That is distinguishable at a glance from siblings like convert_tree or validate_tree, which transform or check rather than open.

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?

Usage is only implied — the reader can infer this is the tool for getting a shareable/editable link, and 'Fails with the validation errors if the tree has any' hints that validate_tree may be a precursor. But no sibling is named and there is no explicit when-to-use-this-instead-of-convert_tree guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The description adds genuine context beyond that: the output is behavior3 JSON and the response shape switches between a list and a single tree depending on whether id is supplied. It does not say what happens for an unknown id or whether the list is paginated.

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?

Two sentences, no filler, with the content inventory first and the mode behavior second. The parenthetical example list is slightly long but earns its place by showing what kinds of trees are available. Nothing is buried or redundant.

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 one-optional-parameter read tool with full annotation coverage and no output schema, this is enough to call correctly: the agent knows both modes, the return format, and that no id is required. Nothing material is missing.

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 coverage is 100% and the single parameter already documents 'Example id from the list; omit to list them'. The description restates this as a list-versus-fetch switch, which clarifies the consequence of omission but duplicates what the schema already says. Baseline 3 is appropriate when the schema does the heavy lifting.

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 gives a concrete verb and resource ('returns that tree as behavior3 JSON') and characterizes the resource content with real examples (enemy patrol, cooldown-gated attacks, robot navigation). It also spells out the dual-mode behavior, listing versus fetching by id. It stops short of naming a sibling like read_guide or list_node_types, so the boundary is inferred rather than stated.

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?

It states the two usage contexts clearly: call with no id to browse available examples, or with an id to fetch one. The framing 'to learn the format from or start with' signals the intended workflow. It offers no explicit exclusion guidance against the similar-sounding read_guide or list_node_types, which is the only gap.

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

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

The annotations already establish that this is a safe, read-only, idempotent, closed-world operation. The description adds useful content context by saying the result covers composites, decorators, and leaves with descriptions and default properties, though it does not detail the response structure.

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 definition is a single, information-dense sentence with no filler, and it front-loads the node-type scope before enumerating examples. The parenthetical examples and ellipses make it slightly busy, but every element contributes useful context.

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 parameterless, read-only listing tool with rich annotations and no output schema, the description is nearly complete: it explains what categories and metadata are returned. More explicit guidance on when an agent should call this versus other reference tools would make it fully complete.

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?

There are zero input parameters, so the baseline is 4 under the rubric. The description appropriately does not invent parameter semantics where none exist.

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 identifies the exact resource: built-in behavior3 node types grouped into composites, decorators, and leaves, and notes that descriptions and default properties are included. It is clear enough to distinguish this from sibling tools such as validate_tree or convert_tree, though it does not explicitly name an alternative or state the listing verb.

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?

Usage is implied by the phrase 'a tree can use without declaring them,' suggesting this is the discovery/reference tool for available built-in nodes. However, it gives no explicit when-to-use guidance, no exclusions, and no comparison with siblings like read_guide or get_example.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and remote-fetch profile is covered structurally. The description adds useful context beyond that: results are Markdown and a slug-less call returns a listing rather than content. It does not say what happens with an invalid slug or whether guide payloads are truncated.

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?

Two sentences, front-loaded with the source and return format, then a dense topic list that genuinely aids topic-matching. The enumeration is long but each entry is a distinct searchable subject, so little is wasted.

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?

With one optional parameter, no output schema, and rich annotations, the description covers what an agent needs: source, return format, and the no-slug listing mode. Only edge behavior (invalid slug, response size) is left unstated, which is minor at this complexity.

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 coverage is 100% and the single slug parameter is described there as "Guide slug from the list; omit to list them." The description restates the omit-to-list behavior and implies the slug comes from the listing, but adds no format or validation detail beyond the schema. Baseline 3 applies.

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?

States a specific verb+resource: reads practical behavior tree guides from behaviortrees.com/learn and returns them as Markdown. The topic list scopes exactly which content lives here (node types, blackboards, engine integrations) so an agent can distinguish it from get_example or list_node_types, though it never names those siblings explicitly.

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 final sentence, "Without a slug, lists the guides," gives explicit conditional usage for the two modes (list vs. fetch), which is the main decision an agent faces here. It stops short of naming alternatives such as get_example or list_node_types as the preferred tools for those narrower needs.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the bar is lower; the description still adds real value by naming every validation rule applied and stating what the response contains (valid flag, trees found, findings at error/warning/info). It stops short of saying the tree is never mutated or how findings are ordered, but the check inventory is unusually concrete.

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?

Two sentences, front-loaded with the validation scope and followed by the return shape. The error enumeration is dense but every item is a distinct check that earns its place.

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?

With no output schema, the description compensates by naming the three return components, which is what an agent needs to interpret results. Combined with the fully documented input schema and read-only annotations, only minor gaps remain, such as whether it repairs anything or how findings map to specific nodes.

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% and the single `tree` parameter already carries an extensive description covering behavior3 JSON, whole projects, and BehaviorTree.CPP XML. The tool description adds nothing about the parameter, so the baseline of 3 is correct.

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 opens with a specific verb and resource ("Checks a behavior tree for errors") and then enumerates the exact error classes it detects: dangling children, multi-parent nodes, cycles, arity violations, unknown node names, and BehaviorTree.CPP import problems. That specificity clearly separates it from siblings like convert_tree or list_node_types.

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 intent is implied clearly enough that an agent would call it before converting or rendering a tree, but there is no explicit when-to-use or when-not guidance and no mention of alternatives. It does not, for example, tell the agent to call list_node_types first to learn built-in names, even though the error list includes unknown node names.

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