Aggregate UNDP project funding

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

With no annotations provided, the description carries the full burden of disclosing behavior. It states that the tool aggregates server-side, covers a full year, and returns totals and counts, which is a clear read-only query profile. It does not mention authorization, rate limits, or default sort/limit behavior, but for a read-only aggregation tool this is a reasonable level of disclosure.

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?

Two sentences achieve both clarity and economy: the first packs the core behavior and output, the second provides concrete use cases and a contrast with paging. There is no fluff, and the most decision-relevant information is front-loaded.

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?

For a tool with 7 parameters and no output schema, the description gives enough context to select and invoke it correctly: the aggregation behavior, return fields, and example use cases. Minor gaps remain, such as the default behavior when group_by is omitted and the effect of limit, but these do not prevent an agent from making a correct first call.

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?

The schema already covers year, region, group_by, donor_country, and operating_unit with descriptions (71% coverage), and the description adds meaning by illustrating the group_by dimensions and tying them to example questions. However, limit and sort_by have no schema descriptions and the description does not explain them either, leaving a gap that is only partially compensated.

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 ('Aggregate a full year of UNDP projects') and enumerates the grouping dimensions and return fields (totalled budget, expenditure, project counts). It further differentiates from sibling tools by emphasizing server-side summarization 'instead of paging through thousands of projects', making the tool's role unmistakable.

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?

It gives concrete example questions ('which countries got the most funding in 2023', 'how much did Germany fund') and contrasts with the alternative approach of paging through projects. While this clearly implies 'use this instead of search_projects for aggregate questions', it does not explicitly name that sibling or state exclusions like 'do not use this for individual project details'.

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