Score Facility

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 behavioral context: the score is 'independent,' only existing facilities are eligible, and the score covers seven named dimensions plus composite/tier/peer outputs. No contradiction with annotations exists.

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 dense but every sentence earns its place: use case, example, parameter summary, return summary, and explicit exclusions. The primary trigger is front-loaded, and the no-use cases are clearly separated at the end.

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?

The tool is a read-only scoring operation with an output schema and fully documented parameters. The description covers when to use it, what it returns, what the weighting options mean, and which sibling tools to prefer in related but distinct scenarios. Nothing an agent needs to invoke it correctly is missing.

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 the schema already documents both facility_id and weighting including the default. The description adds a concrete example and restates the weighting options, but it also introduces 'facility_id or name' while the schema only defines facility_id, creating a minor inconsistency. The added value over the schema is modest.

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 a specific verb ('score'), a specific resource ('ONE existing facility'), and a precise output ('independent 0-100 grade across 7 dimensions'). It also distinguishes itself from siblings like analyze_site, compare_sites, and find_alternatives, so an agent can select it correctly without opening other definitions.

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 opens with 'Use when a user wants...' and explicitly lists exclusions with alternative tools: raw lat/lon parcels should use analyze_site, multi-site comparisons should use compare_sites, and similar-site searches should use find_alternatives. This gives the agent both positive and negative routing guidance.

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