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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the full safety profile. The description adds content scope (what categories of public works data are exposed), which is genuinely useful context, but says nothing about filtering, scope, or output behavior beyond the annotation baseline.

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 short and front-loads the domain label at the start, which is good. But the colon-separated fragment list is cryptic rather than economical — it omits the sentence structure that would make the categories unambiguously interpretable.

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?

An output schema exists, so return values need no explanation, and the read-only annotations make the safety story complete. What is missing is the core action and its relationship to the many sibling tools, leaving the agent to infer the tool's role from a keyword list.

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?

Only one parameter (api_key) exists and it is fully documented in the schema as an alternative to the Authorization header, so no description-side explanation is needed. With full schema coverage and no meaningful functional parameters, the baseline is high.

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 names a resource domain (public works) and enumerates its facets — settlement level progression, open construction, standing buildings, catalog — so an agent can guess it surfaces city-building state. However, it is a noun-phrase fragment with no verb, leaving it unclear whether the tool lists, queries, or summarizes. It also does nothing to separate it from siblings like city, my_city, or list_open_councils.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. With close siblings such as city and my_city present, an agent has no stated basis for choosing city_projects over them. The description only implies a general context at best.

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