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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the tool operates on OSM data and that the bounding box order is (south, west, north, east), but does not disclose other behavioral traits such as pagination, rate limits, or default sorting. With annotations carrying most of the burden, this is adequate but not exceptional.

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 two sentences, front-loaded with the primary action and resource, followed by two relatable examples and the coordinate order. Every sentence carries essential information, with no filler or repetition. It is exceptionally concise and well-structured.

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's simplicity (read-only POI query), the description explains what it does, when to use it, and a critical parameter detail. An output schema exists, so return values are already documented. The description is self-sufficient for an agent to select and invoke the tool correctly without additional context.

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 coverage is 100%, so all parameters are individually documented. The description adds value by explicitly stating the bounding box order: '(south, west, north, east)'—a critical detail that the schema does not convey as a sequence. This helps agents correctly map coordinates to the south/west/north/east parameters.

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 a specific verb and resource: 'Find OSM POIs inside a bounding box.' It clearly distinguishes from sibling tools like pois_near by emphasizing the geometric approach (bounding box) and provides concrete examples ('every park in this area'). This goes beyond a generic statement and ties directly to the tool's function.

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 explicit use cases: 'Use for "every park in this area" or "all restaurants in this neighborhood"'. It implies when to use this tool versus alternatives (e.g., radius-based search), though it does not name specific alternatives or explain when not to use it. The given scenarios are clear and actionable.

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