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

With readOnlyHint=true and openWorldHint=false already in annotations, the description goes well beyond them: it discloses that NAICS and POPGROUP use dictionary value lists while other dimensions are enumerated live, that roughly half of dictionary codes return no rows and are dropped, that the response source field indicates whether that check ran, and that dictionary lists can run to thousands of codes. This is substantial behavioral context no structured field provides.

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 front-loaded with the core purpose in the first sentence, then adds necessary behavioral nuance in a dense but efficient way. Every sentence earns its place: routing logic, dictionary filtering behavior, query guidance, and output usage. There is no filler or repetition of schema content.

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's complexity — six parameters, vintage-dependent behavior, and schema with full coverage and output schema — the description covers the key decision points: which dimensions follow which enumeration route, why codes are dropped, how to handle large result sets, and how to feed results back into predicates. The read-only annotation covers safety, and the output schema removes the need to describe return shape. Nothing an agent needs to invoke it correctly seems 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 description coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning: it explains how the predicate parameter relates to the tool's output ('Pass the returned code as the dimension's value in predicates'), and it contextualizes query as the practical narrowing mechanism for large dictionaries. It does not restate each schema field, but it clarifies the purpose and output usage of the parameters beyond the schema alone.

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: 'List the codes a Census filter dimension accepts.' It immediately ties the purpose to the unresolved question left by census_query_data or census_compare_geographies, and names the sibling tools (census_list_datasets, census_search_variables) where relevant. An agent can clearly distinguish this from searching variables or querying data.

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 says when to use this tool: when a predicates map needs to be written without guessing or when another tool reports a dimension was left unset. It gives concrete routing guidance based on vintage and dimension, explains when a keyword is the practical way to use it, and tells the agent to pass the returned code into predicates. It also indirectly tells when not to rely on this tool's dictionary path by noting dictionary lists are shared classifications, not dataset-specific result sets.

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