hatch_searchFilter Hatch cases near a point by country/text. Approximate geocode.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| lat | Yes | ||
| lng | No | ||
| lon | No | ||
| country | No | ||
| radius_km | No |
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| cases | No | ||
| limit | No | ||
| filter | No | ||
| citations | Yes | ||
| provenance | Yes |
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Input schema / anyOfAdded value: +[
+ {
+ "required": [
+ "lon"
+ ]
+ },
+ {
+ "required": [
+ "lng"
+ ]
+ }
+]Input schema / properties / lon / maximumAdded value: +180Input schema / properties / lon / minimumAdded value: +-180Input schema / properties / radius_km / maximumAdded value: +20000Input schema / requiredPrevious value: -[
- "lat",
- "lon"
-]New value: +[
+ "lat"
+]Output schema / properties / casesAdded value: +{
+ "type": "array"
+}Output schema / properties / doctrineRemoved value: -{
- "type": "string"
-}Output schema / properties / filterAdded value: +{
+ "type": "object"
+}Output schema / properties / limitAdded value: +{
+ "type": "string"
+}Output schema / properties / nAdded value: +{
+ "type": "integer"
+}Output schema / properties / provenance / properties / neverAdded value: +{
+ "type": "string"
+}Output schema / requiredAdded value: +[
+ "citations",
+ "provenance"
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide strong behavioral hints: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by noting the geocoding is approximate, which is important behavioral context. No contradictions with annotations.
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 very concise at 8 words, front-loading the key verb 'Filter' and resource 'Hatch cases'. The single sentence efficiently conveys the core purpose. Could benefit from slightly more structure or examples.
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 tool has 6 parameters (moderate complexity), 0% schema coverage, but does have an output schema and rich annotations, the description is minimally adequate. It doesn't explain the output format, error cases, the radius_km boundary meaning (20000 km is half the Earth), or the ambiguous lon/lng field.
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 fully. It explains the purpose of the coordinates (point near which to filter), the country parameter, and the text parameter. However, it doesn't explain the unique 'lon' vs 'lng' choice, the semantics of 'radius_km', or the text search behavior. High reliance on parameter names alone.
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 clearly states the tool filters Hatch cases by proximity to a point, constrained by country and text. The phrase 'Approximate geocode' provides useful accuracy expectations. However, it doesn't differentiate from the sibling tool 'nearby_cases' which may have similar geographic filtering.
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 gives no guidance on when to use this tool versus alternatives like 'nearby_cases', 'hatch_stats', or other search tools. It doesn't mention prerequisites, required coordinate format preferences (lon vs lng), or when text filtering is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.