mcp/tests/test_tool_description_boundaries.py

import unittest

from tools.export_out_of_province_port_data import (
    ExportOutOfProvincePortDataTool,
)
from tools.export_pallet_data import ExportPalletDataTool
from tools.export_pending_outbound_orders import ExportPendingOutboundOrdersTool
from tools.list_order_filter_options import ListOrderFilterOptionsTool
from tools.list_pending_outbound_export_filter_options import (
    ListPendingOutboundExportFilterOptionsTool,
)
from tools.query_customs_declaration_files import QueryCustomsDeclarationFilesTool
from tools.query_order import QueryOrderTool
from tools.query_order_detail import QueryOrderDetailTool
from tools.query_order_exact import QueryOrderExactTool
from tools.query_outbound_detail import QueryOutboundDetailTool
from tools.query_outbound_list import QueryOutboundListTool
from tools.query_destination_trailer_list import QueryDestinationTrailerListTool
from tools.list_destination_trailer_filter_options import (
    ListDestinationTrailerFilterOptionsTool,
)
from tools.query_track import QueryTrackTool


class ToolDescriptionBoundaryTest(unittest.TestCase):
    def test_every_existing_tool_states_use_and_prohibition_boundaries(self):
        tools = (
            QueryOrderTool(),
            QueryOrderExactTool(),
            QueryTrackTool(),
            QueryCustomsDeclarationFilesTool(),
            QueryOutboundListTool(),
            QueryOutboundDetailTool(),
            ListOrderFilterOptionsTool(),
            ListPendingOutboundExportFilterOptionsTool(),
            ExportPendingOutboundOrdersTool(),
            ExportOutOfProvincePortDataTool(),
            ExportPalletDataTool(),
            QueryDestinationTrailerListTool(),
            ListDestinationTrailerFilterOptionsTool(),
        )

        for tool in tools:
            with self.subTest(tool=tool.name):
                description = tool.metadata()['description']
                self.assertIn('使用场景：', description)
                self.assertIn('禁止使用：', description)

    def test_number_tools_require_clarification_and_forbid_trial_queries(self):
        tools = (
            QueryOrderTool(),
            QueryOrderExactTool(),
            QueryTrackTool(),
            QueryCustomsDeclarationFilesTool(),
            QueryOutboundListTool(),
            QueryOutboundDetailTool(),
            ExportOutOfProvincePortDataTool(),
            ExportPalletDataTool(),
            QueryDestinationTrailerListTool(),
        )

        for tool in tools:
            with self.subTest(tool=tool.name):
                description = tool.metadata()['description']
                self.assertIn('号码类型不明确时必须先询问用户', description)
                self.assertIn('不得根据号码格式猜测', description)
                self.assertIn('不得跨字段或跨工具试查', description)

    def test_result_intent_distinguishes_adjacent_tools(self):
        expected = {
            QueryOrderTool(): ('旧版跨字段通用搜索', 'query_order_exact', '订单列表'),
            QueryOrderExactTool(): ('订单列表', 'query_order_detail', '排舱列表'),
            QueryOrderDetailTool(): ('单个订单的详情', '逐个调用', 'query_order_exact', '订单列表'),
            QueryTrackTool(): ('物流轨迹', '订单资料', '报关资料文件'),
            QueryCustomsDeclarationFilesTool(): ('报关资料文件', '完整排舱详情', '文件链接'),
            QueryOutboundListTool(): ('排舱列表', '40个字段', '排舱详情'),
            QueryOutboundDetailTool(): ('排舱详情', '11项汇总', '38项订单明细'),
            ListOrderFilterOptionsTool(): ('query_order_exact', '授权筛选值', '业务数据'),
            ListPendingOutboundExportFilterOptionsTool(): (
                'export_pending_outbound_orders', '授权筛选值', 'query_outbound_list',
            ),
            ExportPendingOutboundOrdersTool(): ('明确要求导出', '未排舱订单', '查看或查询'),
            ExportOutOfProvincePortDataTool(): ('明确要求导出', '省外进港资料', '普通排舱查询'),
            ExportPalletDataTool(): ('明确要求导出', '打托数据', 'query_export_task'),
            QueryDestinationTrailerListTool(): (
                '海外提柜', 'query_outbound_list', '六个类型',
            ),
            ListDestinationTrailerFilterOptionsTool(): (
                'query_destination_trailer_list', '禁止猜测', '排舱列表',
            ),
        }

        for tool, phrases in expected.items():
            with self.subTest(tool=tool.name):
                description = tool.metadata()['description']
                for phrase in phrases:
                    self.assertIn(phrase, description)

    def test_outbound_number_fields_require_explicit_business_types(self):
        properties = QueryOutboundListTool().metadata()['input_schema']['properties']
        for field, label in (
            ('outbound_numbers', '排舱单号'),
            ('order_numbers', '订单号'),
            ('container_codes', '柜号'),
            ('so_numbers', 'SO号'),
            ('bl_numbers', '提单号'),
        ):
            with self.subTest(field=field):
                description = properties[field]['description']
                self.assertIn(label, description)
                self.assertIn('仅当用户明确', description)
                self.assertIn('不得放入其他类型号码', description)

    def test_export_tools_describe_async_follow_up_without_long_wait(self):
        for tool in (
            ExportPendingOutboundOrdersTool(),
            ExportOutOfProvincePortDataTool(),
            ExportPalletDataTool(),
        ):
            with self.subTest(tool=tool.name):
                description = tool.metadata()['description']
                self.assertIn('异步导出任务', description)
                self.assertIn('query_export_task', description)
                self.assertIn('不会在本次调用中等待文件生成', description)


if __name__ == '__main__':
    unittest.main()