Global Metro Power Rankings

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

With no annotations provided, the description carries the full behavioral burden. It discloses the comparison structure (side-by-side, leader flagged per dimension) and scope (all sixteen dimensions). However, it doesn't describe return format, how ties are handled, whether the output is tabular or narrative, or any ordering behavior. For a read-only comparison tool, this is adequate but could disclose more about the output structure.

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?

A single sentence that efficiently conveys the tool's purpose, scope (2-4 metros), granularity (all sixteen dimensions), and the leader-flagging behavior. Zero waste, front-loaded with the main action.

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 has one parameter (fully documented in schema), no annotations, no output schema, and no nested objects. The description covers the core behavior well. However, since there's no output schema and no annotations, the description could disclose more about the output format (how the leader flag is presented, what fields appear in each comparison row) to fully compensate. It's functional but leaves some ambiguity about the result structure.

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 single 'slugs' parameter is fully documented with minItems 2 and maxItems 4 constraints in the schema. The description's 'two to 4 metros' and 'sixteen scoring dimensions' adds a little context but doesn't go beyond what the schema already conveys about constraints. Baseline 3 is appropriate when the schema does the heavy lifting for a single well-documented parameter.

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 clearly states the tool performs a side-by-side comparison of 2-4 metros across all sixteen scoring dimensions, flagging the leader in each. The verb 'compare' plus the resource scope ('metros') is specific. However, it doesn't explicitly distinguish from the sibling tools like get_metro (single metro details) or list_top_metros (ranking), though the comparison nature is fairly distinct by name.

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 conveys the tool takes 2-4 metros for comparison, which implies it's used when a comparative view is desired. However, there's no explicit guidance on when to use this vs alternatives (e.g., when to use search_metros first to find slugs, or when get_metro would suffice for a single metro). The 'across all sixteen scoring dimensions' adds some context but no explicit exclusions or alternatives are named.

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

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

With no annotations provided, the description carries the full burden of disclosure. It clearly indicates this is a read-only explanatory tool returning methodology details, with no mention of mutation, side effects, or destructive behavior. The description adequately conveys what the agent should expect: a breakdown of dimensions, weights, and data sources. It reasonably implies a stable, non-destructive operation.

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 a single, information-dense sentence that packs in multiple details: what is returned (sixteen weighted dimensions), the context (Global Metro Power Rankings composite score), and the granularity of information (what each measures, weight/shape, upstream source). It is front-loaded with the subject and purpose. Slightly long but every clause 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, no-output-schema tool, the description is quite complete. It tells the agent what content to expect (dimensions, weights, data sources) without needing to enumerate every dimension. The complexity is moderate, and the description adequately sets expectations for what the tool delivers. It could theoretically enumerate the sixteen dimensions, but that level of detail is unnecessary for tool selection.

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 has 0 parameters, and schema description coverage is 100%. With no parameters, the baseline is 4 per the rubric. The description adds value by describing what content will be returned, which compensates for the absence of any parameter semantics to clarify.

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 clearly states the tool returns the sixteen weighted dimensions behind the Global Metro Power Rankings composite score. It specifies what each dimension measures, its weight/shape in the formula, and its upstream data source. This is a specific verb+resource and clearly distinguishes itself from sibling tools like get_metro or list_top_metros which deal with metro data, not methodology.

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 implicitly communicates its purpose as an explanatory/reference tool distinct from the data-returning siblings. However, it doesn't explicitly state when a user should call this instead of alternatives (e.g., 'Use this when you need to understand how scores are calculated, not the actual rankings'). The context is clear but lacks explicit when-to-use guidance.

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

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

No annotations are provided, so the description carries the burden for behavioral disclosure. The description does reveal the scope of data returned and the requirement to know the slug, but doesn't mention pagination, performance characteristics, or how errors manifest for invalid slugs. The enumerated content list gives reasonable expectations, warranting a mid score.

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, front-loaded with the exhaustive content list followed by a targeted usage directive. Every sentence earns its place with zero filler or repetition.

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 only one parameter that is 100% schema-covered, no output schema, and no nested objects, the tool is simple. The description enumerates the return contents thoroughly and provides usage prerequisites. Since no annotations exist, the description adequately compensates for the missing safety/behavior context for a presumably read-only data retrieval tool.

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 the slug parameter with format examples ('new-york', 'london'). The description reinforces that the slug must be known/exact and even names the alternative tool to find it, which slightly adds context beyond schema. Baseline 3 is appropriate given the schema does the heavy lifting.

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 precise verb+resource ('Full profile for one metro') and enumerates the specific data dimensions returned (rank, score, sixteen dimension values/ranks, teams, universities, culture, etc.). Clearly distinguishes from search_metros (which finds metros) and list_top_metros (which lists multiple).

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?

Explicitly instructs to 'Use search_metros first if you don't know the exact slug,' which directly addresses the primary prerequisite and routes to the correct sibling tool for lookup scenarios. This is clear when-to-use guidance with an explicit alternative.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the output format (lightweight summary rows with listed fields) and the cap of 200 rows per call, which is useful. However, it omits potential behavioral details such as pagination, behavior on empty results, error handling, or whether filters are exact/case-sensitive, leaving some ambiguity for an agent.

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 two sentences with no fluff. It front-loads the core purpose, mentions the source and scale, lists the output fields, points to an alternative, and states the row cap—all efficiently. Every sentence earns its place, making it highly concise and well-structured.

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 simple list tool with no output schema, the description provides sufficient context: the source, filters, output fields, and row limit. It also directs the agent to get_metro for detailed data, which covers the main use case. It does not mention sorting order (implied by 'ranked') or edge-case behavior, but these are minor gaps given the tool's simplicity.

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 description coverage is 100%, so the parameters (n, region, country) are already well-documented in the input schema. The description only reiterates that filtering by region or country is optional and mentions the cap, which is already in the schema. It adds minimal semantic value beyond what the schema provides, so a baseline score of 3 is appropriate.

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 clearly states the tool's function: it returns a ranked list of metros from a specific composite, with optional filters by region or country, and describes the output fields. It also distinguishes itself from get_metro by explicitly pointing to that tool for full detail, making the purpose unambiguous.

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 gives a clear usage hint by saying 'Call get_metro for full detail on any one metro,' which implicitly tells the agent when to use this list tool versus the detail tool. However, it does not explicitly mention when to use alternatives like search_metros or compare_metros, nor does it state when not to use this tool, so it stops short of full exclusionary guidance.

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

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

Discloses the case-insensitive behavior of the search, which is a meaningful behavioral trait not conveyed by annotations. However, no annotations exist, so the description carries full burden. It doesn't describe matching semantics beyond fields searched (fuzzy, prefix, substring) or what results return, leaving some ambiguity for the agent.

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, both load-bearing. The first states functionality and scope; the second provides workflow context tying to sibling tools. Zero waste.

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 simple 2-param search tool with a clear output (list of metros with slugs), the description is essentially complete. It covers what's searched, case-insensitivity, and downstream usage. Minor gap: doesn't describe return ordering or that results may be partial, but these are minor for a discovery-oriented search tool.

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% — the 'query' parameter has a meaningful example ('san fran', 'brazil') in the schema itself, and 'limit' has default/max/min constraints documented. The description adds little beyond the schema but examples are provided by the schema, warranting baseline. The description does clarify the query targets name, primary city, and country, adding some semantic value.

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?

Description uses a specific verb ('case-insensitive search') over concrete resources (metro name, primary city, country). It clearly distinguishes itself from siblings by stating it's the way to find a metro's slug before calling get_metro or compare_metros.

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?

Explicitly states when to use this tool ('Use this to find a metro's exact slug before calling get_metro or compare_metros'), providing clear context and a workflow for why search precedes those tools. This effectively scopes its purpose relative to siblings.

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