mcp_iati_list_activity_statuses

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

With no annotations present, the description carries the full burden, and it does well by framing the call as non-mutating and specifying the return contents: 'status code', 'human-readable label', and 'number of activities'. It could add more edge-case behavior, such as what happens when no IATI data is loaded, but the read-only nature and output shape are transparent.

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 front-loaded with the primary purpose, then usage, return shape, and relevant IATI terminology, keeping the most actionable information early. It is slightly redundant by later restating 'activity statuses' as 'lifecycle statuses', but every section otherwise earns its place.

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 zero-parameter, non-mutating list tool with an output schema present, this description is complete: it explains the data scope, the intended use, the return columns, and the domain vocabulary. An agent has enough to decide when to call it and what to expect.

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 tool accepts zero parameters, so the input schema already describes everything that can be passed; the 0-param baseline is 4. The description adds useful context by scoping the result to the currently loaded IATI dataset, which helps even with no arguments.

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 names a specific verb ('List') and a specific resource ('activity statuses present in the loaded IATI data'), then clarifies they are lifecycle statuses. This resource is distinct from sibling list tools such as list_sectors or list_reporting_organisations, so an agent can tell which list is intended without opening schemas.

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 explicitly says to use the tool 'before filtering or analysing activities' to discover which lifecycle statuses are available, providing clear context for when it is useful. It does not name alternative tools or state when not to use it, so it falls just short of fully explicit routing.

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