cats_projects_near

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does add useful interim behavior: 'Queries both the point layer ... and the line layer ... and merges the results,' and it describes the return dict. However, it does not mention potential error conditions, geocoding dependency for addresses, result ordering, or limits. For a read-only search tool, this is acceptable but not comprehensive.

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 front-loaded with the core purpose, followed by a concise layer-merging detail and a compact Args list. The format is a bit longer than strictly necessary but every sentence earns its place; the Args contributions clarify parameter semantics not present in the schema. No unnecessary fluff or repetition.

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?

Given the absence of an output schema and annotations, the description compensates by explicitly listing the return fields (resolved location, project list, summary) and the two-layer behavior. It covers the primary usage modes and parameters. It lacks edge-case handling (e.g., what happens with no results or invalid coordinates), but for a relatively simple spatial search tool, this 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?

Even though the schema coverage is 0%, the description's Args section fully explains each parameter. It states that address is used instead of lat/lon, clarifies the mutual exclusivity ('Provide this OR lat/lon'), and gives the default for radius_m. This adds significant semantic meaning beyond the bare schema types and defaults, making parameter usage unambiguous.

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 opens with 'Find CATS (Charlotte Area Transit System) capital projects near an address or coordinate,' which clearly names the specific resource (CATS capital projects) and the action (find near location). It also explicitly notes that it queries both point and line layers, further distinguishing it from sibling tools like cip_projects_near or crime_near. This is a specific verb+resource+scope statement.

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 implies when to use the tool (for CATS projects near a location) and explains the address-or-coordinate input modes, but it does not explicitly contrast it with alternatives such as cip_projects_near or mention any exclusions. Usage context is clear enough for an agent to select it for transit-related proximity searches, but direct guidance against using other tools is absent.

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