List Organizations

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

The annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: the ~907 node scope, the free tier, the cgac warning that it is 'NOT the same code space as awarding_agency_code', the direct-children-only behavior of parent_id, and the search minimum length of 2 chars. This materially improves an agent's ability to use the tool correctly.

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 well-structured with a clear opening sentence and bulleted parameter explanations. It is longer than minimal but nearly every line adds useful context, such as the code-space warning and the limit cap. Minor redundancy exists between the opening usage sentence and the search bullet, preventing a perfect score.

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 an 8-parameter tool with no schema descriptions, the description covers the core workflow, pagination via parent_id, and important integration caveats. The output schema exists, so return value documentation is not required. The main gaps are the undocumented is_active and offset parameters, which leave a small but real completeness hole.

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?

With schema description coverage at 0%, the description carries the burden and explains six of eight parameters: type, cgac, parent_id, hierarchy_level, search, and limit. The cgac explanation is especially valuable. However, is_active and offset receive no explanatory text, so the coverage is strong but not complete.

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: 'Search the federal agency organization tree (~907 departments/agencies/offices).' It clearly distinguishes this from related siblings such as get_organization and lookup_agency by framing it as the search/list entry point over the hierarchy tree.

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 usage context: 'Market Research tool. Use search to resolve a name/acronym to an org, or parent_id to list an agency's direct sub-units.' It also explains how to chain results to get_organization or page through children. It does not explicitly enumerate when not to use this tool versus siblings like lookup_agency or discover_offices, so it stops short of a 5.

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