get_children

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

With no annotations, the description carries the full burden. It discloses that the tool returns compact summaries, explains the input format (IRI or short ID), and warns against branch names. It also specifies the return structure as a JSON array. However, it does not explicitly state that the tool is read-only/non-destructive, though the 'Get' verb implies this.

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 concise and front-loaded: a one-sentence summary followed by labeled Args and Returns sections. Every line adds value, including the branch-name warning and the max_depth recommendation. No filler or redundancy.

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 simple tool with two parameters and no annotations, this description covers purpose, parameter semantics, return format, and alternatives. It also includes a practical hint about result size. The guidance is sufficient for an agent to invoke the tool correctly without additional context.

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%, so the description must compensate. It thoroughly explains the iri parameter with examples and an exclusion (not a branch name), and describes max_depth with its default and a performance suggestion. This adds significant meaning beyond the raw 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 opens with 'Get child concepts of a FOLIO concept,' clearly specifying the verb and resource. It also distinguishes itself from siblings like get_taxonomy_branch and get_concept, making its 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 explicitly tells users what not to do: 'NOT a branch name — use get_taxonomy_branch for branch names.' It also advises keeping max_depth at 1-2 to avoid large results and directs users to get_concept for full details, providing clear alternatives.

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