Get Investment Score

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

With no annotations, the description carries the full burden and does well: it discloses that the formula is never returned, that accessibility and risk come back as not_available, that the score is relative to available factors, and that it costs one API call. It does not describe auth requirements or what the error looks like for an unsupported country, which is the main remaining gap.

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?

Front-loaded with the core deliverable and zero filler sentences; every clause carries information (scale, rating values, factor levels, country scope, cost). The middle sentence is a dense run-on covering three separate facts, which costs a little readability.

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?

There is no output schema and no annotations, so the description must explain the return value — and it does, specifying the 0-100 scale, the rating enum, the factor-level enum, and which factors may be not_available. Combined with the country-support constraints and the one-call cost hint, an agent has everything needed to call it and interpret the response.

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 100%, so both parameters are already documented, including the country enum with auto-detect behavior. The description repeats the country list rather than adding new parameter-level meaning (no reference-format guidance, no note on how country changes the result set beyond availability). Baseline 3 is correct.

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?

States a specific verb+resource (investment score for a parcel) with the output scale (0-100) and rating vocabulary, and implicitly differentiates itself from factor-level siblings like get_solar_potential, get_agriculture and get_market_data by explaining that it is built from them. An agent can distinguish it from every sibling without opening a schema.

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?

Gives clear context for when the tool applies: supported countries (ES, PV, NA, PT, FR, IT, DE), the narrower country scope of the market factor, and an explicit exclusion ('Other countries are not supported'). It never explicitly says 'use this instead of get_solar_potential when you want an aggregate', so the routing guidance is implied rather than stated.

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