kite-connect-mcp

Authorise holdings for sale (dry run by default)

authorise_holdings

Destructive

Start CDSL demat authorisation for selling shares, including after a SELL fails with HTTP 428. Preview requests by default, then send with a confirmation token to get the TPIN authorise URL.

Instructions

Start a CDSL authorisation so that shares can be sold from the demat account. Call this when a SELL fails with HTTP 428 ('N quantity needs authorisation at depository'). DRY RUN BY DEFAULT: with dry_run=true (the default) nothing is sent; the answer shows the request and the checks. Repeat the identical call with dry_run=false and the confirmation_token to send it: Kite answers with a request_id, and this tool's live answer then contains authorise_url, the link YOU open in a browser to key in your demat PIN (TPIN) at CDSL. The PIN never passes through this server. Nothing is authorised until you finish that page.

With holdings (isin and quantity pairs) only those shares are authorised; without it the page offers the entire holdings. An authorisation is valid for one trading session (until 5:30 PM IST, then it counts for the next trading day) and is used up as you sell. This is not an order: no caps apply.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "authorise_holdings"
  }
}

Input Schema

Name	Required	Description
`dry_run`	No	true (default): validate and preview only, nothing is sent. false: send it live, which needs live trading enabled on the server and the confirmation_token from a dry run
`holdings`	No	the holdings (isin, quantity) to authorise; omit to authorise the entire holdings
`confirmation_token`	No	the confirmation_token returned by a dry run of this exact call (single use)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: dry_run is default-on so nothing is sent, live mode requires a single-use confirmation_token from the matching dry run, the live response carries authorise_url, the TPIN never touches the server, nothing is authorised until the page is completed, and the authorisation lasts one trading session until 5:30 PM IST and is consumed by selling. This is exactly the mutating, non-idempotent, open-world behaviour the annotations only flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the trigger condition and the dry-run default, which are the two facts that decide the call. It runs long and repeats a little of the schema (isin/quantity pairs), but essentially every sentence carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain return values — and it does, naming the dry-run preview, the live request_id, and authorise_url, plus the human step needed to finish. An agent has everything required to run the two-step flow correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds relational meaning the schema can't express: the dry_run/confirmation_token pairing must be the identical call, and omitting holdings authorises the entire holdings rather than nothing. It mostly restates the isin/quantity semantics that the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Start a CDSL authorisation so that shares can be sold from the demat account' — and immediately separates it from order placement ('This is not an order: no caps apply'), so an agent won't confuse it with place_order or get_holdings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger condition: call this when a SELL fails with HTTP 428 ('N quantity needs authorisation at depository'). It also names the exclusion ('this is not an order') and the alternative path (the CDSL browser page), leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.