get_udf_lists

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action and that no parameters are required, but doesn't disclose return format, pagination, performance implications, or whether it's a read-only operation. For a list operation, an agent might need to know if the list is large or requires iteration, but the description offers no such context.

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 one sentence, front-loaded with the action and resource, and includes a useful parenthetical about the underlying NBAPI wrapper. The extra note 'No parameters required' is redundant given the empty schema, but harmless. It's concise and well-structured.

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?

Given the tool has zero parameters and no output schema, the description covers the essential input side. However, it doesn't describe what the return value looks like (e.g., a list of UDF list objects with IDs and names), which an agent might need to know for downstream processing. The sibling 'get_udf_list_items' hints at a hierarchy, but the description doesn't clarify the relationship or what fields are returned. Still, for a simple no-param list operation, it's mostly 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?

The tool has zero parameters, and the schema has no properties, so there's no parameter documentation needed. The description explicitly states 'No parameters required,' which is clear and accurate. With 0 parameters, the baseline is 4 as per the rubric, and the description meets it.

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 it lists user-defined field (UDF) lists configured on the NetBox system, with a specific verb ('Lists') and resource ('UDF lists'). It distinguishes itself from the sibling 'get_udf_list_items' which likely lists the items within a UDF list, and other get_* tools. However, it doesn't explicitly differentiate itself from all siblings or mention the NBAPI wrapper context beyond a parenthetical.

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 provides no explicit guidance on when to use this tool versus alternatives. The context implies it's for retrieving UDF lists, and the sibling 'get_udf_list_items' suggests a related tool, but no direct comparison or conditions are stated. With many sibling tools, a brief 'use this to fetch all UDF lists; for individual items use get_udf_list_items' would be helpful.

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