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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely valuable behavioral context beyond that: the RERA-verified filter, the straight-line (not driving) distance semantics, that each result includes the nearest metro station and distances to all 4 IT hubs, and the geographic scope of each hub option. It stops short of a 5 by omitting edge-case behavior such as no-results fallbacks or result-count limits, though the output schema partially compensates for return-value details.

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?

Every section earns its place: purpose, routing triggers, parameter options with mappings, and result contents. The trigger examples and the it_hub list serve distinct purposes (NLU matching vs. value mapping) rather than duplicating each other. The information is front-loaded and structured with clean section markers and arrow notation, making it dense but scannable.

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 that an output schema exists (covering return structure) and annotations cover the read-only safety profile, the description is nearly complete: it covers purpose, routing, all documented parameter semantics, distance units, defaults, and result contents. The remaining holes are the two unreported parameters and the lack of guidance on fallback behavior when no projects match, which leaves an agent slightly under-equipped for edge-case handling.

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 carries the full burden — and it delivers for the two parameters it covers. it_hub lists all four exact string values with geographic mappings ('electronic_city' → Electronic City Phase 1 & 2, etc.), and max_dist_km is thoroughly explained as straight-line km from the hub centroid with a default of 10 and a suggested 5–15 range. The gap is that the context signal reports 4 parameters while the description documents only 2, leaving the other two undocumented in both the schema and the description.

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 opening sentence is a model purpose statement: specific verb ('Find'), specific resource ('RERA-verified Bangalore projects'), and a distinguishing method ('by proximity to a major IT hub'). It is immediately differentiable from sibling tools like search_fulltext, search_projects, and get_builder_projects, whose purposes do not involve commute proximity.

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, actionable trigger conditions: 'Use this when the user mentions their workplace or asks about commute convenience,' reinforced with concrete user-phrase examples ('I work in Electronic City', 'short commute to ORR / Sarjapur Road') and a directive to prefer it over web search. However, it never contrasts this tool with the closest sibling alternatives, search_projects and search_fulltext, so an agent receives no guidance on when NOT to use it in favor of those.

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