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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds one real behavioral fact — the output is codes destined for get_data's select — but says nothing about match semantics (substring vs prefix vs fuzzy), empty-result behavior, or the default limit of 20, all of which affect how an agent should phrase a query.

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?

Two short sentences, front-loaded with the action and scope, and the em-dash example ('a suburb name in a geography dimension') does real work by making 'label text' concrete. No filler or restated title.

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?

The output schema exists, so return values need not be spelled out, and the description correctly points at get_data as the consumer of the codes. What is missing is the navigation context an agent needs in this multi-tool set: where 'table' and 'dimension' values come from (describe_table/search_tables), and any hint about result volume given the limit parameter.

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 coverage is only 25%, with just 'query' documented ('Match against option codes and labels'), so the description must partly compensate — and it does explain that matching is against label text within a dimension of a table. But 'table', 'dimension' and especially 'limit' get no added meaning beyond their names and constraints, leaving the parameter layer thin.

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?

Names a specific verb and resource ('Find option codes by label text') and bounds the scope to 'one dimension of one table', which separates it from search_tables and get_data. It stops short of explicitly contrasting with the sibling 'search' tool, so an agent could still hesitate between the two.

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?

Usage is implied rather than stated: the closing sentence 'Returns codes to use in get_data's select' tells the agent the downstream purpose, which is genuinely useful routing context. However, there is no explicit when-not guidance, no mention of how the table/dimension identifiers are discovered (describe_table, search_tables), and no signposting against the sibling 'search' tool.

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