A reference Go implementation of the Agent-to-Agent (A2A) protocol with multi-agent system support, MCP tool integration, and various agent configurations
a2a-go exhibits severe definition quality issues across nearly all tools. While 16 tools are declared, source code inspection reveals NO visible input schemas, parameter descriptions, or structured output documentation. Tool descriptions are present but extremely brief (10-30 chars), failing the 10-1024 char guidance and providing minimal LLM decision support. The codebase uses github.com/mark3labs/mcp-go, but tool implementations in pkg/tools/*.go lack explicit schema registration patterns. Names follow verb_noun convention adequately (azure_get_*, azure_create_*, etc.), but parameter constraints, type definitions, and error recovery guidance are completely absent. Without visible schemas and descriptions, tools are effectively non-functional for LLM integration.
No input schemas visible for any tool. Cannot determine parameter types, constraints, or required fields. LLMs cannot invoke tools safely without schema information.
Tool descriptions are all 10-30 characters (e.g., 'Azure DevOps tool to retrieve sprint information'). These are far too brief to guide LLM selection between similar tools (e.g., azure_get_sprints vs azure_sprint_overview vs azure_sprint_items are confusingly close). Missing WHEN to use, WHAT data it returns, and dependencies on other tools.
browserdocker
Recommendations
ADD DETAILED INPUT SCHEMAS: Every tool must declare input parameters with JSON Schema types (string, number, boolean, array, object), not just names. Use mark3labs/mcp-go's schema builders explicitly. Example: azure_get_sprints should declare parameters like project_id (string, required), iteration_path (string, optional), top (integer 1-200, default 20).
EXPAND TOOL DESCRIPTIONS TO 100-200 CHARS: Replace 'Azure DevOps tool to retrieve sprint information' with 'Fetch all sprints (iterations) in an Azure DevOps project, including start/end dates and status. Use this to discover available planning cycles before querying items. Returns sprint_id, name, start_date, end_date, status.'
DISAMBIGUATE WORK ITEM TOOLS: Rename or clarify: azure_get_work_items (fetch by array of IDs), azure_search_work_items (free-text or WIQL query), azure_find_items_by_status (filtered by status only). Add to descriptions: 'Use this when you have specific work item IDs' vs 'Use when you need to search by criteria' vs 'Use for status-only filtering.' This prevents LLM confusion.
ADD PARAMETER DESCRIPTIONS: Every parameter needs a 50-100 char explanation. Example: 'project_id (string): Azure DevOps project key or name (e.g., "MyProject"). Required.', 'top (integer): Max items to return, 1 - 200. Default 20. Use higher values for large queries, lower for quick previews.'
DOCUMENT OUTPUT SCHEMAS: Add to each tool description what fields are returned and their types. Example for create_sprint: 'Returns object with sprint_id (string), name (string), start_date (ISO 8601), end_date (ISO 8601), status (string: "future"|"current"|"past")'.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Sampling (deprecated) - integrate directly with the LLM provider API
Score history
Overall score trend
↑ 32 points across a rubric change (v1 → v2)
32/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
32
<=2025-11-25
v2
2026-03-09
F
0
-
v1
Azure DevOps tool to retrieve work items
azure_search_work_itemsread onlyauth30/100
Azure DevOps tool to search for work items
azure_sprint_itemsread onlyauth32/100
Azure DevOps tool to retrieve items within a sprint
azure_sprint_overviewread onlyauth32/100
Azure DevOps tool to get sprint overview and metrics
azure_update_work_itemswriteauth32/100
Azure DevOps tool to update existing work items
azure_work_item_commentswriteauth30/100
Azure DevOps tool to manage work item comments
browserread only30/100
Browser automation tool for web interaction and content extraction
catalogread onlysource verified27/100
Agent catalog tool for discovering and querying available agents
dockerdestructiveauth30/100
Docker container management and orchestration tool
Multiple tools operate on work items (azure_get_work_items, azure_create_work_items, azure_update_work_items, azure_search_work_items, azure_find_items_by_status, azure_enrich_work_item) with nearly identical names. Baseline: successful tools make distinctions obvious (e.g., get_user vs get_user_permissions vs list_users). These names conflate into ambiguous clusters. LLMs will struggle to pick the right one.
No parameter descriptions visible in source code. Rubric baseline: 100% of A+ tools have descriptions for every parameter. Without param descriptions, LLMs cannot infer whether a 'filter' param is a JSON string, regex, enum, or free-text; they guess wrong.
No documented output schemas. Rubric baseline: 100% of A+ tools have documented return types. Without output documentation, LLMs cannot extract chaining IDs (e.g., sprint_id from create_sprint result) for downstream calls, forcing extra lookups and wasting context.
Destructive tools (docker, azure_create_*, azure_update_*, azure_enrich_work_item, azure_work_item_comments) lack error recovery guidance. Rubric pattern:recovery-guide requires: 'Error responses must tell the LLM what to do next.' No evidence of dry-run, confirmation, or rollback mechanisms.
No evidence of pagination support for list-like tools (azure_get_sprints, azure_sprint_items, azure_get_work_items, azure_search_work_items). Rubric baseline: tools returning lists must accept page/offset/limit and return a total count. Without pagination, large result sets exhaust context windows.
ADD ERROR RECOVERY GUIDANCE: For destructive tools (azure_create_*, azure_update_*), include in description: 'If this fails, check Azure DevOps permissions. If partially succeeds, use azure_update_work_items to fix individual items.' For docker, add: 'Provide container ID or name. Returns error if container not found, suggest list_containers first.'
IMPLEMENT PAGINATION: Add limit and offset (or page/pageSize) parameters to list tools. Document: 'Default limit=20. Max limit=200. Returns total_count and has_more flag for client-side iteration.'
ADD ENUM CONSTRAINTS FOR STATUS FIELDS: Instead of free-text 'status' parameters, declare enums in schema. Example: azure_find_items_by_status should accept status enum: ['future', 'current', 'past'] for sprints, or ['New', 'Active', 'Resolved', 'Closed'] for work items.
REDUCE REQUIRED PARAMETERS: Make project_id and other context parameters optional if the server can infer them from environment or prior agent state. If required, provide smart defaults or offer a discovery tool (list_projects) first.
ADD IDEMPOTENCY HINTS: For azure_create_* tools, document if they're idempotent (safe to retry with same input) or if they create duplicates. If not idempotent, offer an upsert variant or explicit deduplication.
VALIDATE INPUTS EARLY: Return clear 400-level errors with actionable guidance, not 500 stack traces. Example: 'Invalid status "pend", must be one of: New, Active, Resolved, Closed. Did you mean "Active"?'
ADD TOOL ANNOTATIONS: Use mcp-go's toolAnnotations to mark destructive tools (docker, azure_create_*, azure_update_*) with destructiveHint=true and read-only tools with readOnlyHint=true. Helps clients warn users before execution.