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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds meaningful context beyond the annotations by specifying exactly what metadata fields are returned (columns, types, row count, category, last-updated). It does not contradict the annotations and provides useful information about the return value, which is sufficient for a simple read-only retrieval operation.

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 sentence that front-loads the action ('Get') and the resource, immediately followed by the return fields and the input example. Every word earns its place, and there is no redundancy or filler. It is compact yet informative.

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 tool with one required parameter, rich annotations (read-only, idempotent), and no output schema, the description fully covers what the tool does and what it returns. It lists the key metadata fields and gives a concrete example of the input. There is no ambiguity about the tool's behavior, making it complete for its simple scope.

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?

The schema already covers 100% of the single parameter, stating that resource_id is a 'Dataset id, e.g. "cjeq-bs86"'. The description repeats this example and adds that it's a Cook County Open Data resource, but does not add any new meaning beyond what the schema provides. With full schema coverage, the baseline is 3, and the description doesn't elevate it further.

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 is very specific: 'Get a Cook County Open Data dataset's schema + metadata (columns, types, row count, category, last-updated) by resource_id'. The verb 'Get' clearly indicates retrieval, and the resource is precisely scoped to the dataset metadata for a given resource_id. It also distinguishes itself from sibling tools like 'datasets' and 'query' by focusing on schema and metadata rather than listing datasets or running data queries.

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 provides clear context by defining the input (resource_id) and the output (columns, types, row count, etc.), implying it should be used when one needs dataset structural information. However, it does not explicitly state when not to use it or mention alternatives, such as using 'query' for actual data retrieval or 'datasets' for finding available datasets. This is a minor gap but the use case is clear enough for a single-parameter metadata lookup tool.

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