singapore_query_museum_visitors

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral note — results report source coverage from a bundled catalog and coverage may be stale — but says nothing about result size, ordering defaults, or failure modes.

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?

Three tight sentences: purpose and dataset id first, then capabilities, then the coverage caveat. Every sentence carries information an agent would otherwise lack.

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?

With an output schema present, the description needn't explain return values, and it covers the essential pre-call step (inspect the dataset for field names) plus a data-freshness caveat. The main omission is not clarifying how this specialized querier relates to the generic singapore_query_dataset sibling.

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 50% (q, sort, filters documented; fields, limit, offset bare). The description maps to all six parameters at a high level ('exact filters, column text search, fields, sort and pagination'), but adds no syntax or format detail beyond the schema's own examples, so it neither compensates for nor worsens the coverage gap.

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 and resource ('Query Visitorship to National Museums and Heritage Institutions'), plus the owning agency and topic, which separates it from generic siblings like singapore_query_dataset and from the distinct singapore_query_visitor_arrivals. It stops short of explicitly naming which sibling to use when a generic dataset query is also viable.

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 a concrete workflow prerequisite: inspect dataset d_618a1224b896b436ce650be1f77c804e first for filter fields, and fetch metadata for current coverage. It also enumerates the supported operations (exact filters, column text search, fields, sort, pagination), but offers no when-not or alternative-tool routing.

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