Skip to main content
Glama

Trustbase Lab · Trusted Data Infrastructure for the AI Era

by com.trustbaselab
OverviewDiscussionsAdmin

Trade Partner Ranking

get_trade_partner_ranking
Read-onlyIdempotent

Purpose: rank partner countries for one reporter, period and flow direction by quantity, returning rank, partner, quantity, value, unit price and share. Guidelines: reporter (ISO3 alpha), period (YYYY) and flow (X =export, M = import) are required; raise top_n above the default 10 (max 50) only when a longer tail is needed.Limits: one reporter-period-flow combination per call; World aggregate rows are excluded; shares are computed within the returned set, not against global trade. Ex: get_trade_partner_ranking(reporter='CHN', period='2025', flow='X'), get_trade_partner_ranking(reporter='USA', period='2024', flow='M', top_n=20).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
flowNo流向 X=出口/M=进口
top_nNoTop N 伙伴国（默认 10,最大 50）
periodYes期间 YYYY（必填,如 2024）
reporterYes报告国 ISO3，必要
response_formatNoOutput format: 'markdown' (default, human-readable) or 'json' (machine-readable).markdown

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
textYesHuman-readable result (markdown, or a JSON string when response_format=json).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / response_format / description
      Added value: +"Output format: 'markdown' (default, human-readable) or 'json' (machine-readable)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "text": {
+      "description": "Human-readable result (markdown, or a JSON string when response_format=json).",
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral detail: World aggregate rows are excluded, shares are computed only within the returned set, and only one reporter-period-flow combination is allowed per call. This goes well beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-organized into Purpose, Guidelines, Limits, and Ex sections. Every sentence adds information, and the most important scoping details appear first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description is nearly complete: it gives purpose, required parameters, limitations, share semantics, and concrete examples. The only gap is the inconsistent requiredness of flow between the description and the input schema, which could mislead an agent during invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds useful nuance for flow values, top_n default/max, and usage examples. However, it states that flow is required while the schema's required array only lists reporter and period, creating a conflicting signal that prevents a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Purpose: rank partner countries for one reporter, period and flow direction by quantity' and lists the exact return fields ('rank, partner, quantity, value, unit price and share'). This is a specific verb+resource that clearly differentiates the tool from siblings like get_trade_flow_summary and query_trade_flows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states required inputs (reporter, period, flow), when to raise top_n ('only when a longer tail is needed'), and the one-call-per-combination limit. It lacks explicit alternatives or when-not-to-use guidance, so it stops short of a 5, but the context is clear.

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

All Trustbase Lab · Trusted Data Infrastructure for the AI Era toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources