get_guarantors
Identify guarantor entities for a bond to assess guarantee coverage and structural subordination risks using CUSIP or bond identifier.
Instructions
Find all entities that guarantee a bond. Use to understand guarantee coverage and structural subordination risk. Pass a CUSIP or bond description.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bond_id | Yes | Bond CUSIP or identifier |
Implementation Reference
- debtstack/mcp_server.py:477-498 (handler)Main handler logic for get_guarantors tool. Takes bond_id from arguments, makes POST request to /entities/traverse API with relationship type 'guarantees' and inbound direction, formats entities using format_entity() helper, and returns formatted text with guarantor information.
elif name == "get_guarantors": bond_id = arguments.get("bond_id", "").strip() body = { "start": {"type": "bond", "id": bond_id}, "relationships": ["guarantees"], "direction": "inbound", "fields": ["name", "entity_type", "jurisdiction", "is_guarantor"] } result = api_post("/entities/traverse", body) data = result.get("data", {}) start = data.get("start", {}) entities = data.get("traversal", {}).get("entities", []) text = f"**Guarantors for {start.get('name', bond_id)}**\n\n" if not entities: text += "No guarantors found." else: text += f"{len(entities)} guarantor(s):\n\n" text += "\n".join(format_entity(e) for e in entities) return [TextContent(type="text", text=text)] - debtstack/mcp_server.py:296-313 (schema)Tool registration with input schema for get_guarantors. Defines the tool name, description, and required parameter 'bond_id' (string) which accepts Bond CUSIP or identifier.
Tool( name="get_guarantors", description=( "Find all entities that guarantee a bond. " "Use to understand guarantee coverage and structural subordination risk. " "Pass a CUSIP or bond description." ), inputSchema={ "type": "object", "properties": { "bond_id": { "type": "string", "description": "Bond CUSIP or identifier" } }, "required": ["bond_id"] } ), - debtstack/mcp_server.py:157-174 (helper)Helper function format_entity() used by get_guarantors to format entity data for display. Shows entity name, type, jurisdiction, guarantor status, VIE status, and debt at entity level.
def format_entity(e: dict) -> str: """Format entity data for display.""" name = e.get('name', 'Unknown') etype = e.get('entity_type', 'entity').replace('_', ' ').title() jurisdiction = e.get('jurisdiction', '') parts = [f"• {name} ({etype})"] if jurisdiction: parts[0] += f" - {jurisdiction}" if e.get('is_guarantor'): parts.append(" ✓ Guarantor") if e.get('is_vie'): parts.append(" ⚠️ VIE") if e.get('debt_at_entity'): parts.append(f" Debt: ${e['debt_at_entity'] / 100_000_000_000:.2f}B") return "\n".join(parts) - debtstack/mcp_server.py:196-415 (registration)The list_tools() function that registers all MCP tools including get_guarantors. This is where the tool is exposed to MCP clients.
@app.list_tools() async def list_tools() -> list[Tool]: """List available DebtStack tools.""" return [ Tool( name="search_companies", description=( "Search companies by ticker, sector, leverage ratio, and risk flags. " "Use to find companies with specific characteristics, compare leverage across peers, " "or screen for structural subordination risk. " "Example: 'Find tech companies with leverage above 4x'" ), inputSchema={ "type": "object", "properties": { "ticker": { "type": "string", "description": "Comma-separated tickers (e.g., 'AAPL,MSFT,GOOGL')" }, "sector": { "type": "string", "description": "Filter by sector (e.g., 'Technology', 'Energy')" }, "min_leverage": { "type": "number", "description": "Minimum leverage ratio" }, "max_leverage": { "type": "number", "description": "Maximum leverage ratio" }, "has_structural_sub": { "type": "boolean", "description": "Filter for structural subordination" }, "limit": { "type": "integer", "description": "Maximum results (default 10)" } }, "required": [] } ), Tool( name="search_bonds", description=( "Search bonds by ticker, seniority, yield, spread, and maturity. " "Use for yield hunting, finding high-yield opportunities, or analyzing maturity walls. " "Example: 'Find senior unsecured bonds yielding above 8%'" ), inputSchema={ "type": "object", "properties": { "ticker": { "type": "string", "description": "Company ticker(s)" }, "seniority": { "type": "string", "enum": ["senior_secured", "senior_unsecured", "subordinated"], "description": "Bond seniority level" }, "min_ytm": { "type": "number", "description": "Minimum yield to maturity (%)" }, "has_pricing": { "type": "boolean", "description": "Only bonds with pricing data" }, "maturity_before": { "type": "string", "description": "Maturity before date (YYYY-MM-DD)" }, "limit": { "type": "integer", "description": "Maximum results (default 10)" } }, "required": [] } ), Tool( name="resolve_bond", description=( "Look up a bond by CUSIP, ISIN, or description. " "Use when you have a partial bond identifier and need full details. " "Example: 'RIG 8% 2027' or 'CUSIP 893830AK8'" ), inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Bond identifier - CUSIP, ISIN, or description (e.g., 'RIG 8% 2027')" } }, "required": ["query"] } ), Tool( name="get_guarantors", description=( "Find all entities that guarantee a bond. " "Use to understand guarantee coverage and structural subordination risk. " "Pass a CUSIP or bond description." ), inputSchema={ "type": "object", "properties": { "bond_id": { "type": "string", "description": "Bond CUSIP or identifier" } }, "required": ["bond_id"] } ), Tool( name="get_corporate_structure", description=( "Get the full corporate structure for a company. " "Shows parent-subsidiary hierarchy, entity types, and debt at each level. " "Use to understand structural subordination and where debt sits in the org." ), inputSchema={ "type": "object", "properties": { "ticker": { "type": "string", "description": "Company ticker (e.g., 'RIG', 'CHTR')" } }, "required": ["ticker"] } ), Tool( name="search_pricing", description=( "Get bond pricing from FINRA TRACE. " "Returns current price, yield to maturity, and spread to treasury. " "Use to find distressed bonds or compare relative value." ), inputSchema={ "type": "object", "properties": { "ticker": { "type": "string", "description": "Company ticker(s)" }, "cusip": { "type": "string", "description": "Bond CUSIP(s)" }, "min_ytm": { "type": "number", "description": "Minimum yield to maturity (%)" }, "limit": { "type": "integer", "description": "Maximum results (default 10)" } }, "required": [] } ), Tool( name="search_documents", description=( "Search SEC filing sections for specific terms. " "Section types: debt_footnote, credit_agreement, indenture, covenants, mda_liquidity. " "Use to find covenant language, credit agreement terms, or debt descriptions." ), inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Search terms" }, "ticker": { "type": "string", "description": "Company ticker(s)" }, "section_type": { "type": "string", "enum": ["debt_footnote", "credit_agreement", "indenture", "covenants", "mda_liquidity", "exhibit_21", "guarantor_list"], "description": "Section type to search" }, "limit": { "type": "integer", "description": "Maximum results (default 10)" } }, "required": ["query"] } ), Tool( name="get_changes", description=( "See what changed in a company's debt structure since a date. " "Returns new issuances, matured debt, leverage changes, and pricing movements. " "Use to monitor companies for material changes." ), inputSchema={ "type": "object", "properties": { "ticker": { "type": "string", "description": "Company ticker" }, "since": { "type": "string", "description": "Compare since date (YYYY-MM-DD)" } }, "required": ["ticker", "since"] } ), ] - debtstack/client.py:698-715 (helper)Convenience method get_guarantors() in the DebtStackClient SDK. Wraps the underlying traverse_entities() primitive with specific parameters for finding guarantors of a bond by CUSIP.
async def get_guarantors(self, cusip: str) -> List[Dict[str, Any]]: """ Get all guarantors for a bond. Args: cusip: Bond CUSIP Returns: List of guarantor entity dictionaries """ result = await self.traverse_entities( start_type="bond", start_id=cusip, relationships=["guarantees"], direction="inbound", fields=["name", "entity_type", "jurisdiction", "is_guarantor"] ) return result.get("data", {}).get("traversal", {}).get("entities", [])