Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server defines 6 tools with basic descriptions and parameter types, but suffers from critical gaps in parameter documentation, schema completeness, and error handling guidance. Most tool parameters lack descriptions explaining what they control or accept. Output schemas are not documented. Error handling provides no recovery guidance. Tool naming is generally acceptable but descriptions are thin (50-80 chars, below the 194 char baseline). Parameter types are present (string, object, array, boolean) but lack constraints (enums, ranges, patterns). The server accepts opaque IDs without accepting human-friendly identifiers (e.g., page names). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite having clear risk profiles. For a production integration with a destructive API (Notion), this is under-engineered.
Tools (6)
create-pagewriteauthsource verified49/100
Create a new page in Notion under a specified parent (database or page).
Parameter descriptions are missing or trivial for all tools. Most parameter descriptions are under 50 characters and provide no actionable guidance. E.g., 'parent' in create-page says 'Parent container for the new page (databaseId or pageId)' but does not specify the required object structure, field names, or format.
No output schemas documented for any tool. LLMs cannot determine what fields to expect, breaking downstream tool chaining. For example, search-notion returns unknown structure; create-page does not document whether response includes the new page_id for follow-up calls.
Expand all tool descriptions to 100-200 characters. Include: WHAT the tool does, WHEN to use it vs. similar tools, WHAT it returns, and any PREREQUISITES. Example: 'Search Notion for pages or databases by title, property, or content. Returns up to 20 results with page_id, title, and created_date. Call this first if you only have a page name; other tools require page_id.'
Add comprehensive parameter descriptions. Every parameter must explain: (1) what it controls, (2) expected format or type, (3) constraints (min/max, regex, enum values), (4) whether it is required or has a default. Example for 'pageId': 'Notion page ID (alphanumeric UUID). Required. Example: 8b5e9a2c-3f6d-4a1b-9c8e-7d2f5a1b9c3e.'
Replace all object-typed parameters with explicit sub-field documentation or nested JSON Schema. For 'properties' in create-page, document valid property names (title, description, status, etc.) and their types. Provide an example: '{"title": [{"text": {"content": "My Page"}}]}'.
Document output schemas for every tool. Include: (1) response object structure, (2) field types and descriptions, (3) IDs and references needed for downstream tool calls. Example for create-page: '{"page_id": string, "title": string, "created_time": ISO8601, "url": string}'.
Add error handling documentation. Describe what errors can occur (not found, unauthorized, rate limited, invalid input) and what the LLM should do: retry, ask user for clarification, or suggest alternatives. Example: 'Error: Page not found. Call search-notion to find the correct page ID.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 0 points across a rubric change (v1 → v2)
42/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-21
F
42
<=2025-11-25
v2
2026-03-09
F
42
-
v1
No error handling or recovery guidance. Tools provide no documentation of how errors are reported (e.g., what happens when a page_id does not exist, or API rate limits are hit). Error responses should tell the LLM what to do next, not just fail silently.
Destructive tools (delete-page, update-page) lack tool annotations and confirmation mechanisms. The rubric requires destructive operations to either support dry-run, declare via toolAnnotations (destructiveHint), or implement confirmation-request pattern. Config has REQUIRE_CONFIRMATION_FOR_DELETE but tool does not expose a 'confirm' parameter.
Tools accept only opaque IDs (pageId, databaseId) and do not support human-readable identifiers (page names, database titles). Users say 'update my project page', not 'update page U2405687'. This forces extra lookup calls and breaks the chat data model.
manage-backups violates composition pattern: one tool with multiple actions (list, restore, cleanup). The 'action' parameter is a free-form string instead of an enum. This should be three separate tools (list-backups, restore-backup, cleanup-backups) so agents compose them as needed.
Object-typed parameters lack internal schema. 'properties' in create-page and update-page, 'filter' in search-notion, and 'parent' in create-page are all objects but have no documented sub-fields, required keys, or types. LLMs cannot know what properties are valid.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite having clear risk profiles. search-notion and generate-context-summary are read-only; create-page, update-page are write; delete-page is destructive. Annotations help agents reason about safety and retry logic.
Tool descriptions are between 40-80 characters, below the 194 char production baseline. Many do not explain WHEN to use the tool, WHAT it returns, or DEPENDENCIES. E.g., 'Generate a context summary' does not explain what context summary means or what fields are included.
No documented idempotency guarantees. Agents retry on failures, non-idempotent tools (create-page, update-page) risk duplicate side effects. Tool descriptions should state: 'idempotent: yes' or document retry behavior.
create-pageupdate-page
Split manage-backups into three separate tools: (1) list-backups (action=list), (2) restore-backup (action=restore), (3) cleanup-backups (action=cleanup). Each tool should accept only its relevant parameters.
Replace free-form string parameters with enums where appropriate. For 'action' in manage-backups, use enum: list|restore|cleanup. For 'type' in generate-context-summary, use enum: database|page.
Add tool annotations to the tool definitions. Use destructiveHint=true for delete-page and update-page; readOnlyHint=true for search-notion and generate-context-summary. This requires modifying the MCP server registration to include these hints (if the current MCP SDK version supports them).
Add support for human-readable identifiers. Modify create-page to accept page_name (resolved to ID internally); modify update-page and delete-page to accept either pageId or page_name. Include a search-by-name hint: 'If you only have a page name, call search-notion first to get the page_id.'
Document idempotency guarantees. For create-page and update-page, state whether duplicate calls with identical input will produce duplicates or return the existing result. Add retry guidance: 'Safe to retry on network errors; may create duplicates if request partially succeeds.'
Add a confirmation/dry-run pattern for destructive tools. Modify delete-page to accept a 'dryRun' parameter (default false). When true, return what would be deleted without executing. Or introduce a separate tool 'preview-deletion' that shows what delete-page would archive.
Document pagination and result limits. If search-notion returns a list, add 'limit' and 'offset' parameters (or 'cursor'). Document the maximum: 'Returns up to 20 results. Use limit (1 - 100) and offset for pagination.'
Add dependency and prerequisite hints. E.g., generate-context-summary: 'Call this after fetching a database schema to understand relationships before querying data.' Or search-notion: 'Call this first if you only know a page name; other tools require page_id.'
Clarify the 'skipBackup' parameter. Document what happens when true: 'If true, skip creating a backup before update/delete. Warning: cannot undo changes without a backup. Default: false (backup created unless explicitly skipped).'
Define the expected format for Notion IDs. Document whether they are: (a) 36-char UUIDs with hyphens, (b) 32-char UUIDs without hyphens, or (c) another format. Provide an example: '8b5e9a2c-3f6d-4a1b-9c8e-7d2f5a1b9c3e'.