get_summarized_crime_data

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

With no annotations, the description carries the burden and does so well: it discloses the default aggregation mode, that partial years are flagged under '_partial_years', and that rates are unweighted averages of available months. It stops short of describing pagination, rate limits, or return structure, but the behavioral detail is notably above 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 summary line is front-loaded and each Args entry earns its place with concrete examples. It is somewhat long, but the added length is informational rather than redundant, so the size is justified.

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?

Because an output schema exists, return values need not be explained, and the description covers all inputs, defaults, and conditional requirements. It could add a brief note on data vintage or caching behavior relative to manage_cache, but for the tool's complexity it is nearly complete.

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 0%, so the description must compensate and it does: every one of the 7 parameters is documented with format examples ('mm-yyyy'), enumerated offense codes, valid level values, and cross-parameter dependencies between level and state/ori. This is exactly what a low-coverage schema needs.

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 states a specific verb and resource ('Get summarized (SRS) crime data') and enumerates the data domains returned (offense rates, actuals, clearances, population coverage). It partially differentiates from siblings by naming SRS data and pointing to get_reference_data, though it doesn't explicitly contrast with get_arrest_data or get_nibrs_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?

It gives concrete conditional guidance: 'state' is required when level is 'state', and 'ori' is required when level is 'agency', plus a pointer to get_reference_data for the offense list. No explicit when-not-to-use guidance or sibling comparison is provided.

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