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_order_abnormal_list import QueryOrderAbnormalListTool
from tools.list_order_abnormal_filter_options import (
    ListOrderAbnormalFilterOptionsTool,
)
from tools.query_goods_info import QueryGoodsInfoTool
from tools.trial_goods_tax import TrialGoodsTaxTool
from tools.query_receive_volume_list import QueryReceiveVolumeListTool
from tools.list_receive_volume_filter_options import (
    ListReceiveVolumeFilterOptionsTool,
)
from tools.query_container_timeliness_list import QueryContainerTimelinessListTool
from tools.query_freightower_track import QueryFreightowerTrackTool
from tools.export_container_timeliness_report import (
    ExportContainerTimelinessReportTool,
)
from tools.query_headhaul_document_list import QueryHeadhaulDocumentListTool
from tools.list_headhaul_document_filter_options import (
    ListHeadhaulDocumentFilterOptionsTool,
)
from tools.prepare_headhaul_document_upload import (
    PrepareHeadhaulDocumentUploadTool,
)
from tools.save_headhaul_document import SaveHeadhaulDocumentTool
from tools.delete_headhaul_document import DeleteHeadhaulDocumentTool
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(),
            QueryOrderAbnormalListTool(),
            ListOrderAbnormalFilterOptionsTool(),
            QueryReceiveVolumeListTool(),
            QueryGoodsInfoTool(),
            TrialGoodsTaxTool(),
            ListReceiveVolumeFilterOptionsTool(),
            QueryContainerTimelinessListTool(),
            ExportContainerTimelinessReportTool(),
            QueryHeadhaulDocumentListTool(),
            ListHeadhaulDocumentFilterOptionsTool(),
            PrepareHeadhaulDocumentUploadTool(),
            SaveHeadhaulDocumentTool(),
            DeleteHeadhaulDocumentTool(),
            QueryFreightowerTrackTool(),
        )

        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(),
            QueryOrderAbnormalListTool(),
            QueryContainerTimelinessListTool(),
            ExportContainerTimelinessReportTool(),
            QueryHeadhaulDocumentListTool(),
            TrialGoodsTaxTool(),
            QueryFreightowerTrackTool(),
        )

        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', '禁止猜测', '排舱列表',
            ),
            QueryOrderAbnormalListTool(): (
                '头程问题件', 'admin/Order/abnormal', 'query_order',
            ),
            ListOrderAbnormalFilterOptionsTool(): (
                'query_order_abnormal_list', '禁止猜测', '作废审核',
            ),
            QueryReceiveVolumeListTool(): (
                '收货量', 'admin/Report/receiveForm', 'query_order',
            ),
            ListReceiveVolumeFilterOptionsTool(): (
                'query_receive_volume_list', '禁止猜测', '导出',
            ),
            QueryContainerTimelinessListTool(): (
                '柜子时效', 'admin/Report/outboundReport', 'query_outbound_list',
            ),
            ExportContainerTimelinessReportTool(): (
                '明确要求导出', '柜子时效', 'query_export_task',
            ),
            QueryHeadhaulDocumentListTool(): (
                '头程文档', 'admin/document/index', 'query_customs_declaration_files',
            ),
            ListHeadhaulDocumentFilterOptionsTool(): (
                'query_headhaul_document_list', '禁止猜测', '报关资料',
            ),
            PrepareHeadhaulDocumentUploadTool(): (
                '对话窗口', '选文件框', '工具参数',
            ),
            SaveHeadhaulDocumentTool(): (
                'ticket_ref', '外链', 'OSS路径',
            ),
            DeleteHeadhaulDocumentTool(): (
                'document_ref', '盲删', '批量删除',
            ),
            QueryFreightowerTrackTool(): (
                '飞驼', 'query_track', '提单号',
            ),
        }

        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(),
            ExportContainerTimelinessReportTool(),
        ):
            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()