Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The NF Curator MCP server has 6 tools with explicit definitions in the @server.list_tools() handler. Schemas are properly structured with type definitions and required fields. However, descriptions are minimal (11-80 chars; baseline is 194 chars at p50), parameter descriptions lack actionable context (especially around format/constraints), and output schemas are completely undocumented. Error handling is present but generic. The server serves a specialized domain (Synapse metadata curation) but does not follow LLM-optimized description patterns. Tools are well-named with clear verbs (synapse_query, fetch_schema, validate_metadata, create_dataset, submit_metadata, get_data_classes), but parameter descriptions are sparse and do not guide the LLM on format, constraints, or dependencies.
Tools (6)
create_datasetwriteauthsource verified73/100
Create a Dataset entity from a Folder (enables SQL queries over files)
fetch_schemawriteauthsource verified66/100
Fetch a JSON schema from the metadata dictionary and optionally save to file
get_data_classesread onlysource verified56/100
Fetch available data class templates from metadata dictionary
submit_metadatawriteauthsource verified63/100
Submit validated metadata by adding annotations to any Synapse entity (dataset, file, folder, etc.)
synapse_queryread onlyauthsource verified63/100
Execute SQL query against a Synapse table to extract metadata
validate_metadataread onlysource verified66/100
Validate JSON metadata against a saved schema file
Tool descriptions are 35 - 80 chars, averaging 51 chars. Baseline is 194 chars (p50). Descriptions lack context on WHEN to use each tool, WHAT it returns, and HOW to chain it with other tools.
Parameter descriptions lack actionable constraints, format guidance, and dependency information. E.g., 'query' in synapse_query says '(use <table_id> as placeholder)' but does not explain valid SQL syntax, result limits, or output structure. 'entity_id' in submit_metadata does not specify format (synXXXX?).
Recommendations
Add output schemas to all 6 tools. Document return type, all fields, and their types. E.g., synapse_query should return {type: 'object', properties: {rows: {type: 'array'}, column_names: {type: 'array'}, row_count: {type: 'integer'}, error: {type: 'string'}}}.
Expand tool descriptions to 120 - 250 chars (baseline p50 = 194). Include: (1) What does the tool do? (2) When to call it instead of a similar tool? (3) What are prerequisites? (4) What does it return? E.g., 'Fetch a JSON schema from the NF metadata dictionary. Call this first before validate_metadata to get the latest schema definition. Returns the schema object and optionally saves to a file. Requires valid schema_name from the metadata registry.'
Add full parameter descriptions with format, constraints, and dependencies. E.g., entity_id in submit_metadata: 'Synapse entity ID in format synXXXX (e.g., syn12345678). Must be a valid Synapse entity (file, folder, or dataset).' query in synapse_query: 'SQL query string using standard SQL syntax. Use {{table_id}} placeholder to reference the table_id parameter. Max 10,000 rows returned; use LIMIT clause for pagination.'
Replace example values with enums or formal constraints. E.g., schema_name should be an enum: {type: 'string', enum: ['PortalDataset', 'PortalPublication', 'PortalFile'], default: 'PortalDataset'}. Move templates_url to server config, not a tool parameter.
Add error handling guidance to tool descriptions. E.g., synapse_query: 'Returns error_code and error_message if query fails. If you get 'Invalid table ID', try list_available_tables(). If you get 'Access denied', verify SYNAPSE_AUTH_TOKEN has read permissions.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Example values appear in descriptions (e.g., fetch_schema: 'e.g., 'PortalDataset', 'PortalPublication'; get_data_classes default URL). Use enums or formal constraints instead.
No error handling guidance in tool definitions. Error responses visible in source code (e.g., SynapseHTTPError handling for annotations) are not exposed to the LLM.
No idempotency or state-modifying warnings for destructive tools. create_dataset, submit_metadata modify state but lack descriptions explaining consequences, recovery options (dry-run), or retry safety.
Parameter 'metadata' in validate_metadata and submit_metadata is typed as 'object' with no schema constraint. LLMs cannot infer required fields, field types, or valid values.
Tool dependencies are undocumented. A workflow likely requires fetch_schema → validate_metadata → submit_metadata, but descriptions do not hint at this ordering.
fetch_schemavalidate_metadatasubmit_metadata
Mark destructive tools (create_dataset, submit_metadata) with state-change warnings in descriptions. E.g., 'WARNING: This modifies the Synapse entity and cannot be undone. Consider validate_metadata first. Returns the updated entity_id and confirmation timestamp.' Add optional dry_run parameter to submit_metadata to show what annotations would be added without committing.
Constrain metadata parameter in validate_metadata and submit_metadata by providing a schema ref or detailed description. E.g., 'Validated JSON metadata object. Must conform to the schema fetched by fetch_schema. Common fields: id (string), name (string), description (string), dataType (enum), isPublic (boolean).'
Add dependency hints to descriptions. E.g., fetch_schema description: 'Fetch the schema before calling validate_metadata. Returns schema in JSON Schema format.' validate_metadata description: 'Use fetch_schema first to retrieve the schema. Validates metadata object against the schema and returns validation errors (if any) or success confirmation.' submit_metadata description: 'Call validate_metadata first to ensure metadata is valid. Adds validated metadata as annotations to the Synapse entity.'
Document pagination and result limits. E.g., if synapse_query or get_data_classes returns lists, add max_results parameter (default 50, max 10000) and return total_count and next_cursor for chaining.
Add missing parameter descriptions. E.g., get_data_classes: 'Fetch available data class templates from the metadata dictionary. Returns a list of templates (name, description, example JSON) that can be used as starting points for validate_metadata.'
Consider adding a 'list_available_schemas' or 'list_available_entities' tool to enable discovery before fetch_schema and submit_metadata.