search_nyc_legistar_matters

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does add a useful behavioral caveat: results must still be verified against the official matter page or enacted local law before acceptance. However, it does not mention authentication, rate limits, pagination, or output shape, which limits transparency for a search tool hitting an external API.

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 concise, with two short sentences; the core purpose is front-loaded and the verification caviat is placed second. Every sentence earns its place, though the brevity leaves out important parameter and usage details.

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 10 optional parameters, no output schema, and no annotations, the description is under-specified. It explains the high-level purpose and reliability caveat but omits essential invocation details such as query syntax, filter semantics, return value shape, and error behavior. An agent would struggle to use all available parameters correctly.

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 input schema has 10 parameters with 0% description coverage, and the tool description provides no explanation of any parameter. It does not clarify what 'q' expects, how filters like status, matter_type, passed_since, or introduced_since behave, what formats are accepted, or how limit/top/timeout_ms interact. The description adds essentially no meaning beyond the bare parameter names.

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 the specific action 'Search' the 'official NYC Legistar matters API' and ties it to 'discovery leads', which clearly identifies what the tool does. It does not explicitly name sibling tools like search_openstates_bills, but the NYC/Legistar scoping makes the resource distinct enough.

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 phrase 'for discovery leads' gives clear context about when this tool is appropriate, and the second sentence warns that results are not final and must be verified before watchlist acceptance. It does not explicitly describe exclusions or alternatives, but the use case is reasonably clear.

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