Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Critical issues: Only 1 tool present (api_call_tool) with severely underdocumented schema and parameters. The tool's input schema shows a generic 'parameters' object with type 'object' but provides NO property definitions, type constraints, or parameter-level descriptions. The tool description itself is minimal (52 chars) and lacks guidance on WHEN to use it, WHAT it returns, or HOW to structure parameters. No error handling documentation. This is a generic API proxy with no specificity, the LLM cannot infer what parameters are valid, what the response structure is, or how to compose multi-step workflows. Hard cap violations apply: input schema has zero documented properties (cannot see actual parameter definitions), and parameter descriptions are completely absent. File: src/tools/api/executor.ts.
Tools (1)
api_call_toolwriteauth13/100
Dynamically generated tool for calling external APIs based on configuration
HARD CAP VIOLATION: Input schema has zero documented parameter properties. Schema field 'parameters' is defined as type 'object' with no 'properties' or 'additionalProperties' constraints. Cannot parse what parameters are valid or expected.
Tool name 'api_call_tool' violates verb_noun convention. Does not start with clear action verb (get_, create_, update_, etc.). Name 'api_call' is generic, LLM cannot infer what specific API is being called or what operation it performs. Should be specific tool names for each API endpoint (e.g., 'kingdee_create_order', 'kingdee_query_items').
HARD CAP VIOLATION: No parameter-level descriptions. Input schema contains 'parameters' object but provides zero documentation of what fields are expected, their types, constraints, or formats. LLM cannot understand parameter semantics.
api_call_tool
Recommendations
Replace generic 'api_call_tool' with specific, action-oriented tools for each Kingdee API endpoint: 'create_purchase_order', 'update_inventory_item', 'query_sales_orders', etc. Each tool should have a clear verb_noun name that tells the LLM exactly what operation it performs.
Document the complete input schema for each tool: list all required and optional parameters, their types (string, number, enum), constraints (min/max, regex patterns), and descriptions. Use JSON Schema properties field with type definitions for every parameter.
Add parameter-level descriptions (50-100 chars each) that answer: What does this parameter control? What format is expected (enum values, date format, numeric range)? Example: 'supplier_id: Unique identifier for the supplier (1-10 digits, e.g., 12345). Required.'
Expand tool descriptions to 100-200 characters explaining: What API operation does this perform? When should I call it instead of a related tool? What data does it return? Example: 'Create a new purchase order in Kingdee. Use this when you have supplier, items, and quantity data. Returns: order_id, creation_timestamp, status.'
Document response/output schema with all returned fields, their types, and purposes. Include IDs that downstream tools will need. Example: { order_id: string, supplier_id: string, items: [ { item_id, quantity, price } ], created_at: ISO8601 string, status: enum }.
Add error handling guidance to each tool description: 'Retryable errors: network timeout, rate limit (retry after 5s). User-fixable: invalid supplier_id (call list_suppliers() first). Fatal: authentication failed (check API credentials).'
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Description is 52 characters and lacks critical context. Does not answer: WHAT API endpoints are available? WHEN should this be called vs others? WHAT is the response structure? HOW do I specify which API to target? Current description is too generic to guide LLM tool selection.
No documented output/response schema. LLM cannot plan downstream tool calls or extract response fields. Tool returns unstructured results without field documentation. Missing: pagination details, field definitions, error structure.
No error handling guidance. No documentation of retryable vs fatal errors, what to do if a parameter is invalid, or how the LLM should interpret failure responses. Code shows basic try-catch but error messages are not user-actionable.
Dynamic API configuration (JSON files in src/tools/api/json/kingdee/) is loaded at runtime, but tool definition does not expose which APIs are available or what their required parameters are. LLM has no way to discover endpoint names or field requirements. This violates the discovery principle, agents need introspectable tool metadata.
No mention of API authentication, secrets management, or how credentials are injected. If the Kingdee API requires tokens or keys, these must not be exposed as tool parameters. Current code does not show secret injection pattern.
Tool has WRITE risk classification but no confirmation/dry-run support documented. Agents calling destructive Kingdee APIs (create, update, delete) have no safety gates. Missing: dry-run mode, confirmation patterns, or undo guidance.
api_call_tool
Implement a discovery/metadata tool that lists all available Kingdee API endpoints and their required parameters. Call it 'list_available_apis' and return: [ { endpoint: 'create_purchase_order', required_params: [...], description: '...' } ]. This enables agents to explore the API surface.
Add dry-run/preview support to all WRITE tools. Accept a 'dry_run: boolean' parameter that validates input and returns a preview of what would be created/modified without actually executing. Destructive operations need safety gates.
Document API authentication and secret injection in the README. Confirm that Kingdee API keys/tokens are injected via environment variables (not tool parameters) and never leaked in responses or logs.
Add pagination parameters (limit, offset/cursor) and response metadata (total_count, next_cursor) to all list/query tools. Cap results at 50 items by default to prevent context window overflow. Document in tool descriptions: 'Results are limited to 50 items. Use offset to fetch additional pages.'
For any parameter that could be ambiguous, provide separate variants: 'supplier_id' for system IDs and 'supplier_name' for human-readable names. Or accept both and try to resolve the name to ID inside the tool.
Validate all parameters early in the executor and return actionable error messages. Instead of a generic 500 error, return: 'Invalid supplier_id: got "abc", must be a numeric ID. Try list_suppliers() to find valid IDs.'
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to the schema. Mark query/list tools as readOnlyHint: true. Mark create/update/delete tools as destructiveHint: true.
Include chaining IDs in responses. If create_purchase_order returns an order_id, ensure that downstream tools like 'add_order_items' or 'approve_order' accept that order_id so agents can compose workflows without extra lookups.