get_changes

Instructions

Implementation Reference

• debtstack/mcp_server.py:560-612 (handler)

  MCP handler for the get_changes tool. Calls API endpoint /companies/{ticker}/changes with 'since' param, then formats the response into a human-readable text string showing new debt, removed/matured debt, metric changes, and summary.

  elif name == "get_changes":
      ticker = arguments.get("ticker", "").upper()
      since = arguments.get("since", "")
      result = api_get(f"/companies/{ticker}/changes", {"since": since})
  
      data = result.get("data", {})
      changes = data.get("changes", {})
  
      text = f"**Changes for {data.get('company_name', ticker)}**\n"
      text += f"Comparing {data.get('snapshot_date', '?')} → {data.get('current_date', 'now')}\n\n"
  
      # New debt
      new_debt = changes.get("new_debt", [])
      if new_debt:
          text += f"**New Debt ({len(new_debt)})**\n"
          for d in new_debt:
              text += f"• {d.get('name', '?')} - ${d.get('principal', 0) / 100_000_000_000:.2f}B\n"
          text += "\n"
  
      # Removed debt
      removed = changes.get("removed_debt", [])
      if removed:
          text += f"**Removed/Matured Debt ({len(removed)})**\n"
          for d in removed:
              text += f"• {d.get('name', '?')} ({d.get('reason', 'removed')})\n"
          text += "\n"
  
      # Metric changes
      metrics = changes.get("metric_changes", {})
      if metrics:
          text += "**Metric Changes**\n"
          for name, vals in metrics.items():
              if isinstance(vals, dict) and 'previous' in vals:
                  prev = vals['previous']
                  curr = vals['current']
                  if isinstance(prev, (int, float)) and isinstance(curr, (int, float)):
                      change = curr - prev
                      sign = "+" if change > 0 else ""
                      text += f"• {name}: {prev} → {curr} ({sign}{change})\n"
          text += "\n"
  
      summary = data.get("summary", {})
      if summary:
          text += "**Summary**\n"
          if summary.get("new_issuances"):
              text += f"• New issuances: {summary['new_issuances']}\n"
          if summary.get("maturities"):
              text += f"• Maturities: {summary['maturities']}\n"
          if summary.get("net_debt_change"):
              change = summary['net_debt_change'] / 100_000_000_000
              text += f"• Net debt change: ${change:+.2f}B\n"
  
      return [TextContent(type="text", text=text)]

• debtstack/mcp_server.py:393-414 (registration)

  MCP tool registration for get_changes. Defines the tool name, description, and input schema (ticker and since date).

  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/langchain.py:274-283 (schema)

  Pydantic input schema GetChangesInput for the LangChain tool, validating ticker (string) and since (date string in YYYY-MM-DD) fields.

  class GetChangesInput(BaseModel):
      """Input for changes tool."""
      ticker: str = Field(
          ...,
          description="Company ticker"
      )
      since: str = Field(
          ...,
          description="Date to compare from (YYYY-MM-DD)"
      )

• debtstack/langchain.py:527-547 (handler)

  LangChain tool class DebtStackGetChangesTool that wraps the API wrapper's get_changes method and returns JSON results.

  class DebtStackGetChangesTool(BaseTool):
      """Get changes to a company's debt structure since a date."""
  
      name: str = "debtstack_get_changes"
      description: str = (
          "Compare a company's current debt structure against a historical snapshot. "
          "Returns new issuances, matured debt, entity changes, leverage changes, and pricing movements. "
          "Use to monitor portfolio companies for material changes or track refinancing activity."
      )
      args_schema: Type[BaseModel] = GetChangesInput
      api_wrapper: DebtStackAPIWrapper
  
      def _run(
          self,
          ticker: str,
          since: str,
          run_manager: Optional[CallbackManagerForToolRun] = None,
      ) -> str:
          result = self.api_wrapper.get_changes(ticker.upper(), since)
          return json.dumps(result, indent=2, default=str)

• debtstack/client.py:630-663 (handler)

  Core SDK async method get_changes that makes the actual HTTP GET request to /companies/{ticker}/changes with a since parameter and returns the raw JSON response.

  async def get_changes(
      self,
      ticker: str,
      since: Union[str, date],
  ) -> Dict[str, Any]:
      """
      Get changes to a company's debt structure since a date.
  
      Args:
          ticker: Company ticker
          since: Compare changes since this date (YYYY-MM-DD)
  
      Returns:
          Dictionary with:
              - new_debt: Newly issued debt since date
              - removed_debt: Matured/retired debt
              - entity_changes: Added/removed entities
              - metric_changes: Changes to leverage, coverage, etc.
              - pricing_changes: Bond price movements
  
      Example:
          result = await client.get_changes(
              ticker="RIG",
              since="2025-10-01"
          )
          for new_bond in result["data"]["changes"]["new_debt"]:
              print(f"New: {new_bond['name']}")
      """
      params = {"since": str(since)}
  
      client = await self._get_client()
      response = await client.get(f"/companies/{ticker}/changes", params=params)
      response.raise_for_status()
      return response.json()