lilbrain_complexity

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool performs complexity analysis and supports both per-function detail and top-N ranking, which implies a read-only analytical operation. However, it does not clarify what the ranking is based on beyond complexity, whether results are scored, or what 'per-function detail' includes.

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 a single, tightly packed sentence with no filler. It front-loads the core metrics and then states the two invocation modes, making it easy to scan and quickly understand the tool's purpose.

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 two-parameter tool with no annotations and no output schema, this is minimally adequate: an agent can infer that omitting name yields a default top-N ranking and that providing name yields per-function detail. However, it lacks detail about output shape, how n and name interact if both are provided, and how this differs from complexity_velocity.

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 the baseline is 3. The description's 'per-function detail or top-N ranking' wording loosely maps to the name and n parameters, but the schema already explains those fields explicitly. The description adds no meaningful semantic information beyond that.

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 identifies the tool as delivering cyclomatic and cognitive complexity analysis, with two modes: per-function detail or top-N ranking. It names specific, non-generic resource types and metrics, though it does not explicitly contrast itself with the closely named sibling lilbrain_complexity_velocity.

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?

There is no guidance on when to use this tool versus alternatives such as lilbrain_hotspots or lilbrain_complexity_velocity. The description implies a complexity-analysis use case but never states exclusions, preferred scenarios, or when another sibling would be more appropriate.

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