cb_monthly_list

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

With no annotations, the description must carry the behavioral burden, and it does substantial work: nightly BoardStat source files, a BetaNYC rebuild rather than the City's official report, and hard scope limits (no ZIP codes, nothing before 2020). It also discloses pagination mechanics and that a page from a newer build is refused via data_as_of. Gaps remain for a query tool of this weight – no statement about result volume, cost, or whether the underlying data lags.

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 purpose and inclusion rules are front-loaded in the first sentence, followed by two short scoping sentences, so nothing is buried. The opening sentence is long and clause-heavy, and the definition is delivered as one undifferentiated block where a list of parts or caveats would scan faster.

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?

Seven parameters and no output schema create a real explanatory burden, and the description compensates by naming the returned fields and the CSV option. Provenance, limits, and pagination are all covered. What is missing is guidance on the data_as_of/next_offset paging loop and any note about freshness lag, both of which an agent would otherwise need to infer.

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 the schema already defines every parameter, and the description largely restates it ('Pages with limit and offset; format csv returns the page as CSV text'). The month default rationale ('the law's immediately preceding month') and the returned-field inventory add modest value, but nothing new is said about the community_district formats or the enum meanings beyond the schema.

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 resource and legal framing ('the monthly list of Charter § 1075(d) ... for one community district') and then enumerates exactly which records are included: new-in-month, still-open earlier requests, and those unresolved at month end but closed since. It also lists the returned fields and scope limits, which lets an agent tell this apart from a generic 311 list without opening the schema. It stops short of naming a sibling it is not, so the top score of 5 is not fully earned.

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 advised: the statute framing, the default month ('the newest complete month'), and the Caveats ('No ZIP codes, nothing before 2020') tell an agent when the tool fits, and the 'part' enum covers the four report variants. Nothing states when to prefer this over the obvious alternatives such as get_service_request_list or find_requests, and there is no explicit exclusion guidance.

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