Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DhanHQ MCP Server start authentication for my DhanHQ account"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for DhanHQ APIs with OAuth-based authentication for Individual Traders.
This server implements the complete three-step DhanHQ authentication flow that generates a JWT access token for API requests. The authentication process involves:
Step 1: Generate Consent - Creates a temporary session ID
Step 2: Browser-Based Login - User authenticates with 2FA
Step 3: Consume Consent - Exchanges tokenId for access token
Related MCP server: Schwab MCP Server
Before you begin, you need to generate your API Key and Secret:
Log in to web.dhan.co
Navigate to My Profile → 'Access DhanHQ APIs'
Toggle to 'API key'
Enter your:
App name
Redirect URL (e.g., http://localhost:3000/callback)
Optional Postback URL
Note: Generated API Keys and Secrets are valid for 12 months.
npm installCopy .env.example to .env and fill in your credentials:
cp .env.example .envDHAN_CLIENT_ID=your_dhan_client_id
DHAN_API_KEY=your_api_key
DHAN_API_SECRET=your_api_secret
REDIRECT_URL=http://localhost:3000/callbacknpm run buildnpm run devThe MCP Inspector provides an interactive interface to test the MCP tools:
npm run inspectorThis will:
Start the MCP server
Open the MCP Inspector in your browser
Allow you to call tools and see responses in real-time
Call the start_authentication tool. This will:
Validate your API credentials
Create a temporary session (consentAppId)
Return a login URL
Open the provided login URL in your browser:
Log in with your Dhan credentials
Complete 2FA verification (OTP/PIN/Password)
You'll be redirected to your configured Redirect URL with a tokenId parameter
Example redirect URL:
http://localhost:3000/callback?tokenId=abc123def456...Call the complete_authentication tool with the tokenId from Step 2:
Exchanges the tokenId for a JWT access token
Stores token details (expiry, client info, etc.)
Returns the access token for use in subsequent API calls
Use check_auth_status to view:
Current authentication state
Token validity
Client information
Token expiry time
start_authenticationInitiates the DhanHQ authentication flow (Step 1).
Input: None
Output: consentAppId, loginUrl, instructions
get_login_instructionsGets the login instructions and URL for Step 2.
Input: consentAppId (optional)
Output: loginUrl, detailed instructions
complete_authenticationCompletes authentication with the tokenId from Step 2 (Step 3).
Input: tokenId (required)
Output: authToken with accessToken and client details
check_auth_statusChecks the current authentication status.
Input: None
Output: Authentication state and token validity
reset_authenticationClears the current authentication state.
Input: None
Output: Success message
Framework: Node.js with TypeScript
Protocol: Model Context Protocol (MCP)
Transport: Stdio
Auth API: DhanHQ OAuth endpoints
HTTP Client: Axios
src/
├── index.ts # MCP server and tool handlers
├── authentication.ts # Authentication logic (3-step flow)
├── config.ts # Configuration management
└── types.ts # TypeScript interfacesAPI credentials are stored in environment variables
Access tokens are stored in-memory (session-based)
For production, use:
Secure credential storage
Database for token persistence
Token refresh mechanisms
HTTPS for callbacks
The MCP Inspector output redacts sensitive tokens
The server includes comprehensive error handling:
API request validation
Network error handling
Configuration validation
Token expiry checking
After authentication is working:
Add API tools for trading operations
Implement token refresh logic
Add portfolio/holdings endpoints
Implement order placement tools
Add market data tools
Logs are printed to stderr for debugging
Authentication state is stored in-memory (lost on restart)
For production, migrate to persistent storage
MCP Inspector is recommended for interactive testing and debugging
MIT
Cancels a pending order. Requires authentication and a valid order ID.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses authentication requirements and that the order must be 'pending,' which adds useful behavioral context beyond the input schema. However, it doesn't cover other traits like whether the cancellation is reversible, rate limits, error conditions, or what happens post-cancellation, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by prerequisites. Every word earns its place with zero waste, making it highly efficient and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is moderately complete. It covers the purpose and prerequisites but lacks details on behavioral traits (e.g., side effects, response format) and doesn't fully compensate for the absence of structured data, making it adequate but with clear gaps for a cancellation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'orderId' fully documented in the schema. The description adds no additional meaning beyond what the schema provides (e.g., no format details or examples). Baseline 3 is appropriate as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancels') and target ('a pending order'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'modify_order' or explicitly mention what makes this tool distinct for cancellation versus modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'Requires authentication and a valid order ID,' which suggests prerequisites but doesn't explicitly guide when to use this tool versus alternatives like 'modify_order' or specify exclusions (e.g., cannot cancel completed orders). It provides some implied guidance but lacks explicit alternatives or when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancels a specific leg of a super order (ENTRY_LEG, TARGET_LEG, or STOP_LOSS_LEG). Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Super order ID | |
| orderLeg | Yes | Which leg to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions authentication requirements, which is useful, but lacks details on behavioral traits such as whether the cancellation is immediate or pending, if it's reversible, what happens to other legs, error conditions, or rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences: one for the purpose and one for authentication. It's front-loaded with the core action, but could be slightly more structured by separating usage notes. There's no wasted text, though it's brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a mutation tool (canceling part of a financial order) with no annotations and no output schema, the description is incomplete. It lacks details on behavior, error handling, or what the tool returns, which are critical for an AI agent to use it correctly in a trading context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (orderId and orderLeg with enum values). The description adds no additional meaning beyond what the schema provides, such as explaining the super order ID format or the implications of canceling each leg type. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancels') and the target ('a specific leg of a super order'), with examples of leg types provided. It distinguishes from sibling tools like 'cancel_order' by specifying it's for a leg of a super order, though it doesn't explicitly contrast with 'modify_super_order' which might be an alternative for adjustments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it's for canceling a leg of a super order, but it doesn't explicitly guide when to use this vs. alternatives like 'cancel_order' (for entire orders) or 'modify_super_order' (for changes other than cancellation). The mention of 'Requires authentication' is a prerequisite, not a usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the current authentication status and returns details about the active access token if available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool checks status and returns token details, which implies it's a read-only operation without side effects. However, it lacks details on error conditions (e.g., what happens if no token is available), rate limits, or specific permissions required, leaving behavioral gaps for a tool that interacts with authentication systems.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action ('Checks the current authentication status') and adds essential detail ('returns details about the active access token if available'). There is no wasted wording, and every part contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (authentication-related with potential security implications), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and return intent but lacks details on output format, error handling, or dependencies (e.g., whether authentication must be started first). For a tool in this context, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description does not discuss parameters, which is appropriate. A baseline of 4 is applied for zero parameters, as it efficiently avoids unnecessary information while matching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Checks') and resource ('authentication status'), and distinguishes it from siblings by focusing on authentication status rather than order/trade operations or authentication initiation/reset. It explicitly mentions what it returns ('details about the active access token if available'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'current authentication status' and 'active access token', suggesting it should be used to verify authentication state, likely before performing operations that require authentication. However, it does not explicitly state when not to use it or name alternatives (e.g., compared to 'start_authentication' or 'reset_authentication'), which prevents a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Completes the authentication flow (Step 3). Takes the tokenId from the redirect URL after browser login and exchanges it for an access token.
| Name | Required | Description | Default |
|---|---|---|---|
| tokenId | Yes | The tokenId received in the redirect URL after browser login (Step 2). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's purpose (completing authentication) and input requirement (tokenId exchange), but lacks details on behavioral traits like error handling, rate limits, security implications, or what happens on success/failure. It adequately describes the core operation but misses advanced context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences: the first states the purpose and step context, the second explains the parameter and outcome. Every word earns its place, and it's front-loaded with the essential action. No wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with 100% schema coverage but no annotations or output schema, the description is reasonably complete. It explains the tool's role in the authentication flow, when to use it, and the parameter's purpose. However, it could better address behavioral aspects like error cases or token lifecycle, given the security-sensitive context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter 'tokenId'. The description adds minimal value by reiterating the parameter's source ('from the redirect URL after browser login') but doesn't provide additional syntax, format, or validation details beyond what the schema states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Completes the authentication flow') and resource ('exchanges it for an access token'), with explicit reference to 'Step 3' distinguishing it from sibling tools like 'start_authentication' and 'reset_authentication'. It precisely defines the tool's role in a multi-step process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Step 3', 'after browser login') and references prerequisites ('tokenId from the redirect URL after browser login'), clearly differentiating it from alternatives like 'start_authentication' (Step 1) and 'check_auth_status'. It provides complete contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves account fund limit information including available balance, margins, collateral, and withdrawable balance. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explicitly stating 'Requires authentication' - a crucial behavioral constraint. It also implies read-only behavior through 'Retrieves' and specifies the scope of returned financial data. However, it doesn't mention potential rate limits, error conditions, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste - the first sentence clearly states purpose and return data, the second adds the critical authentication requirement. Every word earns its place, and the most important information (what it retrieves) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description adequately covers what data is returned and authentication needs. However, it doesn't specify the return format/structure or potential error scenarios, which would be helpful given the financial nature of the data. The absence of annotations means the description should ideally cover more behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage, so the baseline is 4. The description appropriately doesn't waste space discussing non-existent parameters and focuses on what the tool returns instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieves') and resource ('account fund limit information'), and specifies the exact data fields returned ('available balance, margins, collateral, and withdrawable balance'). It distinguishes itself from siblings like get_order_book or get_trade_book by focusing on financial limits rather than order/trade data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While it mentions 'Requires authentication,' it doesn't specify prerequisites like checking auth_status first or differentiate from other financial data tools. No explicit when/when-not scenarios or sibling tool comparisons are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the login instructions and URL for Step 2 (browser-based login). You must complete this step manually by opening the URL in your browser.
| Name | Required | Description | Default |
|---|---|---|---|
| consentAppId | No | The consentAppId from Step 1 (start_authentication). If not provided, the latest one from the current session will be used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: this is a read operation ('Gets'), it requires manual user action ('complete this step manually'), and it's part of a multi-step authentication flow. However, it doesn't mention potential errors, rate limits, or session dependencies beyond the optional parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and front-loaded: the first sentence states the core purpose, and the second sentence provides essential usage guidance. Every word earns its place with no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (part of an authentication flow with manual steps) and lack of annotations/output schema, the description is mostly complete. It covers purpose, usage context, and behavioral expectations well, but could benefit from mentioning what happens if the consentAppId is invalid or if no session exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the single parameter, the baseline is 3. The description adds value by contextualizing the parameter's role in the authentication flow ('Step 2') and implying its relationship to 'Step 1 (start_authentication),' though it doesn't explicitly name the parameter or provide additional syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Gets the login instructions and URL') and resource ('for Step 2 (browser-based login)'), distinguishing it from sibling tools like 'start_authentication' or 'complete_authentication' by focusing on the intermediate login step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('for Step 2') and provides crucial usage context: 'You must complete this step manually by opening the URL in your browser,' which clearly differentiates it from automated authentication tools and sets user expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves all orders placed during the day with their current status. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by specifying authentication requirements and clarifying the scope ('all orders placed during the day'), but lacks details on rate limits, pagination, or error handling. This is adequate but has clear gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with zero waste, front-loading the core purpose. It could be slightly more structured by explicitly stating it has no parameters, but overall it's efficient and well-sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0 parameters, the description is minimally adequate. It covers authentication and scope, but for a tool retrieving 'all orders', it lacks details on return format, data limits, or how 'day' is defined (e.g., timezone), leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is fine here, but it doesn't explicitly state 'no parameters required' to earn a perfect score, leaving minor ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieves') and resource ('all orders placed during the day with their current status'), making the purpose understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'get_order_by_id' or 'get_super_order_book', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires authentication', which provides some context for when to use it, but offers no guidance on when to choose this tool over alternatives like 'get_order_by_id' or 'get_super_order_book'. There are no explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves order status using the user-specified correlation ID. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| correlationId | Yes | Correlation ID used when placing the order |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by stating the authentication requirement, which is useful context beyond the input schema. However, it lacks details on rate limits, error handling, or response format, leaving gaps in behavioral understanding for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences that are front-loaded with the core purpose. It avoids unnecessary details, but the second sentence about authentication could be integrated more smoothly, slightly affecting structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter retrieval), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and authentication need but lacks details on return values, error cases, or usage context, which would enhance completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'correlationId' well-documented. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 where the schema does the heavy lifting without compensating for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieves') and resource ('order status'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_order_by_id' or 'get_order_book', which likely retrieve orders by different identifiers or in bulk, so it doesn't achieve full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions authentication as a requirement, but doesn't specify scenarios where a correlation ID is preferred over other order identifiers or when to choose this over other order-related tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the details and status of a specific order by order ID. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions authentication requirements, which is useful, but lacks details on rate limits, error handling, response format, or whether it's a read-only operation. For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose, using only two sentences. It avoids unnecessary words, though it could be slightly more structured by separating the authentication note into a distinct guideline section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of order retrieval in a financial context with many sibling tools, no annotations, and no output schema, the description is incomplete. It fails to explain what details are returned, how to handle errors, or differentiate from similar tools, leaving the agent with insufficient context for optimal use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents the 'orderId' parameter. The description does not add any meaning beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate when the schema handles parameter documentation effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('retrieves') and resource ('details and status of a specific order'), making the purpose understandable. However, it does not explicitly distinguish this tool from similar siblings like 'get_order_by_correlation_id' or 'get_order_book', which slightly limits differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('Requires authentication') but provides no guidance on when to use this tool versus alternatives such as 'get_order_by_correlation_id' or 'get_order_book'. There is no mention of context, exclusions, or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves all trades for a specific order. Useful for partial fills or bracket/cover orders. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to get trades for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Requires authentication,' which is a useful context for security needs. However, it lacks details on other behavioral traits such as rate limits, error handling, response format, or whether it's read-only (implied by 'Retrieves' but not explicit). For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three concise sentences that each serve a purpose: stating the action, providing usage context, and noting authentication. It is front-loaded with the core purpose, but could be slightly more structured by explicitly separating guidelines. Overall, it is efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a read operation with one parameter) and the absence of annotations and output schema, the description is somewhat complete but has gaps. It covers the purpose and authentication need but lacks details on return values, error cases, or behavioral constraints. For a tool without structured output information, it should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'orderId' clearly documented. The description does not add any additional meaning or context beyond what the schema provides, such as format examples or constraints. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description neither compensates for gaps nor enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('all trades for a specific order'), making it easy to understand what it does. However, it does not explicitly differentiate from sibling tools like 'get_trade_book' or 'get_order_by_id', which might have overlapping functionality, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by mentioning 'Useful for partial fills or bracket/cover orders,' which suggests contexts where this tool is applicable. However, it does not explicitly state when to use this tool versus alternatives like 'get_trade_book' or 'get_order_by_id,' nor does it provide exclusions or clear prerequisites beyond authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves all super orders placed during the day with nested leg details. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the authentication requirement, which is useful behavioral context. However, it lacks details on rate limits, pagination, error handling, or what 'during the day' means (e.g., timezone, date range). This leaves gaps in behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that efficiently convey the purpose and a key requirement. It is front-loaded with the main action and avoids unnecessary words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0 parameters, the description is minimal but covers the basic purpose and authentication need. However, for a tool that retrieves data (implied read operation), it lacks details on return format, scope limitations, or error cases, making it incomplete for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, but since there are no parameters, this is acceptable. Baseline for 0 parameters is 4, as it doesn't need to compensate for missing schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieves') and resource ('all super orders placed during the day with nested leg details'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_order_book' or 'get_super_order' (if that were a sibling), which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires authentication,' which provides some context for usage prerequisites, but it doesn't specify when to use this tool versus alternatives like 'get_order_book' or 'get_super_order' (if applicable). No explicit guidance on when-not-to-use or comparisons is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves all trades executed during the day. Useful for tracking fills and execution prices. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by specifying the scope ('all trades executed during the day') and stating 'Requires authentication', which are useful behavioral traits. However, it lacks details on rate limits, response format, or potential side effects, leaving gaps for a tool that retrieves data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, consisting of three short sentences that efficiently convey purpose, usage, and authentication requirement. Every sentence adds value without redundancy, making it easy to parse quickly. It could be slightly improved by integrating the information more seamlessly, but it's well-structured overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a read operation with no parameters), no annotations, and no output schema, the description is moderately complete. It covers the core purpose and authentication need but lacks details on output format, pagination, or error handling. For a tool that retrieves all trades, more context on what 'all' entails (e.g., time range, limits) would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately avoids discussing any. This meets the baseline for tools with no parameters, as it doesn't mislead or omit necessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('all trades executed during the day'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_order_trades' or 'get_order_book', which might have overlapping functionality, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by stating it's 'useful for tracking fills and execution prices', which implies when to use it. However, it doesn't offer explicit guidance on when to choose this tool over alternatives like 'get_order_trades' or 'get_order_book', nor does it mention any exclusions or prerequisites beyond authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modifies a pending order. Can change price, quantity, order type, and other parameters. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to modify | |
| dhanClientId | Yes | Your Dhan client ID | |
| orderType | Yes | ||
| quantity | No | New quantity | |
| price | No | New price (for LIMIT/STOP_LOSS) | |
| triggerPrice | No | New trigger price (for STOP_LOSS/STOP_LOSS_MARKET) | |
| disclosedQuantity | No | New disclosed quantity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Requires authentication', which is useful, but lacks details on permissions, rate limits, side effects (e.g., order state changes), error handling, or response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences that efficiently cover purpose and authentication requirement. It's front-loaded with the core action and avoids unnecessary details, though it could be slightly more structured by explicitly separating usage conditions from parameter info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., idempotency, error cases), output expectations, and sibling differentiation. The high schema coverage helps, but the description doesn't compensate for missing context in other areas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 86%, with most parameters well-documented in the schema. The description adds minimal value by listing 'price, quantity, order type, and other parameters', but doesn't clarify dependencies (e.g., price relevance to order types) or semantics beyond what the schema provides. Baseline 3 is appropriate given the schema does heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('modifies') and target ('a pending order'), specifying it can change price, quantity, order type, and other parameters. It distinguishes from siblings like 'cancel_order' by focusing on modification rather than cancellation, though it doesn't explicitly contrast with 'modify_super_order'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires authentication' but provides no guidance on when to use this tool versus alternatives like 'modify_super_order' or 'cancel_order'. It doesn't specify prerequisites (e.g., order must be pending) or contextual constraints, leaving the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modifies any leg of a pending or part-traded super order. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Super order ID to modify | |
| dhanClientId | Yes | Your Dhan client ID | |
| legName | Yes | Which leg to modify | |
| orderType | Yes | ||
| quantity | No | New quantity | |
| price | No | New price | |
| targetPrice | No | New target price (for entry leg) | |
| stopLossPrice | No | New stop loss price | |
| trailingJump | No | New trailing jump amount |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions authentication requirement but lacks critical behavioral details: whether this is a destructive/mutative operation (implied by 'Modifies'), what happens on failure, rate limits, or response format. The description is too sparse for a tool with 9 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) and front-loaded with the core purpose. No wasted words, though it could be more structured (e.g., separating authentication note). It efficiently communicates the essential action but lacks depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, mutation operation, no annotations, no output schema), the description is incomplete. It doesn't cover behavioral traits, error handling, or output expectations. For a tool that modifies financial orders, more context on safety and results is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (89%), so the baseline is 3. The description doesn't add meaningful parameter semantics beyond what's in the schema—it doesn't explain relationships between parameters (e.g., 'price' relevance per 'orderType') or usage constraints. However, it doesn't need to compensate heavily given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Modifies'), the target resource ('any leg of a pending or part-traded super order'), and scope ('leg of a super order'). It distinguishes from sibling tools like 'modify_order' by specifying 'super order' context. However, it doesn't explicitly differentiate from 'cancel_super_order_leg' which handles a different modification type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: it mentions 'Requires authentication' but doesn't specify when to use this tool versus alternatives like 'modify_order' or 'cancel_super_order_leg'. No context about prerequisites beyond authentication, nor explicit when-not scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Places a new order on DhanHQ. Requires authentication. Supports MARKET, LIMIT, STOP_LOSS, and STOP_LOSS_MARKET orders.
| Name | Required | Description | Default |
|---|---|---|---|
| dhanClientId | Yes | Your Dhan client ID | |
| correlationId | Yes | Unique correlation ID for order tracking | |
| transactionType | Yes | ||
| exchangeSegment | Yes | e.g., NSE_EQ, BSE_EQ, NFO_FUT | |
| productType | Yes | CNC=Delivery, INTRADAY=Intraday, MARGIN=Margin, CO=Cover Order, BO=Bracket Order | |
| orderType | Yes | ||
| validity | Yes | DAY=Valid for today, IOC=Immediate or Cancel | |
| securityId | Yes | Security ID for the instrument | |
| quantity | Yes | Quantity to order | |
| price | Yes | Price per share (required for LIMIT/STOP_LOSS) | |
| triggerPrice | No | Trigger price (required for STOP_LOSS/STOP_LOSS_MARKET) | |
| disclosedQuantity | No | Quantity visible in order book (min 30% of quantity) | |
| afterMarketOrder | No | Flag for after-market orders | |
| amoTime | No | AMO timing | |
| boProfitValue | No | BO target price change | |
| boStopLossValue | No | BO stop loss price change |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states authentication requirement and supported order types. It lacks critical behavioral details: whether this is a synchronous or asynchronous operation, error handling, rate limits, confirmation mechanisms, or what happens on success/failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. First sentence states core purpose and authentication requirement. Second sentence efficiently lists supported order types. Perfectly front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex order placement tool with 16 parameters, 10 required, no annotations, and no output schema, the description is inadequate. It doesn't explain return values, error conditions, or the operational context needed to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 88% schema description coverage, the schema already documents most parameters well. The description adds minimal value by listing order types, but doesn't explain parameter interactions, dependencies, or business logic beyond what's in schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Places a new order') and target resource ('on DhanHQ'), with specific order types listed. It distinguishes from siblings like 'modify_order' or 'cancel_order' by focusing on creation, though it doesn't explicitly contrast with 'place_super_order'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions authentication requirement but provides no guidance on when to use this tool versus alternatives like 'place_super_order' or 'modify_order'. No context about prerequisites, timing, or trade-offs is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Places a smart super order combining entry, target, and stop-loss legs. Supports trailing stop loss. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| dhanClientId | Yes | Your Dhan client ID | |
| correlationId | Yes | Unique correlation ID for order tracking | |
| transactionType | Yes | ||
| exchangeSegment | Yes | e.g., NSE_EQ, BSE_EQ | |
| productType | Yes | ||
| orderType | Yes | ||
| securityId | Yes | Security ID for the instrument | |
| quantity | Yes | Quantity for entry leg | |
| price | Yes | Entry price | |
| targetPrice | Yes | Target price for profit booking | |
| stopLossPrice | Yes | Stop loss price | |
| trailingJump | No | Trailing stop loss jump amount (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions authentication requirements and the multi-leg nature of the order, but fails to describe critical behavioral aspects: whether this is a read-only or destructive operation, potential side effects, error handling, rate limits, or what happens when the order executes. For a complex trading tool with 12 parameters, this represents a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise at two sentences. The first sentence efficiently states the core functionality, while the second adds the authentication requirement. There's no wasted verbiage, and the information is front-loaded with the primary purpose. The structure could be slightly improved by explicitly mentioning it's for trading/financial orders, but overall it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex trading tool with 12 parameters, no annotations, and no output schema, the description is insufficiently complete. It lacks information about return values, error conditions, order execution behavior, confirmation mechanisms, and how the multi-leg order actually functions. The agent would struggle to use this tool effectively without additional context about what happens after placement and how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal parameter semantics beyond what the schema provides. It mentions 'combining entry, target, and stop-loss legs' and 'Supports trailing stop loss', which helps contextualize parameters like 'targetPrice', 'stopLossPrice', and 'trailingJump'. However, with 75% schema description coverage already documenting most parameters, the description doesn't significantly enhance understanding of individual parameters or their interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Places a smart super order combining entry, target, and stop-loss legs. Supports trailing stop loss.' It specifies the verb ('places'), resource ('smart super order'), and key functionality (multi-leg order with trailing stop). However, it doesn't explicitly differentiate from sibling tools like 'place_order' or 'modify_super_order', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance. It states 'Requires authentication' as a prerequisite, but offers no explicit guidance on when to use this tool versus alternatives like 'place_order' or 'modify_super_order'. There's no mention of specific scenarios, constraints, or comparison with sibling tools, leaving the agent with insufficient context for proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clears the current authentication state and resets the session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'clears' and 'resets', implying a destructive action, but doesn't specify consequences (e.g., loss of access, need to re-authenticate) or requirements (e.g., permissions, side effects like logging out). This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded with the core action ('clears'), making it easy to parse. Every part of the sentence contributes meaning, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an authentication reset tool (a mutation with potential side effects), no annotations, and no output schema, the description is insufficient. It lacks details on behavioral outcomes (e.g., what 'resets the session' entails), error conditions, or return values, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this scenario is 4, as the description appropriately avoids redundant information while focusing on the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('clears', 'resets') and identifies the target resource ('authentication state', 'session'). It distinguishes itself from sibling tools like 'check_auth_status' or 'complete_authentication' by focusing on resetting rather than checking or completing. However, it doesn't explicitly contrast with all siblings, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an active session), exclusions (e.g., not for initial setup), or compare to siblings like 'start_authentication' or 'complete_authentication'. This leaves the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initiates the DhanHQ authentication flow (Step 1). Returns a login URL that you must open in your browser to authenticate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's an initiation action that returns a login URL for browser-based authentication. It doesn't mention rate limits, error conditions, or what happens if authentication is already in progress, but covers the core behavior adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are perfectly front-loaded: the first states the purpose and step position, the second explains the return value and required next action. Every word earns its place with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description provides complete context about what the tool does and how to use its output. It could mention what happens after browser authentication or error cases, but covers the essential workflow adequately given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on the tool's purpose and output behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Initiates the DhanHQ authentication flow') and resource ('authentication flow'), distinguishing it from siblings like 'check_auth_status' or 'complete_authentication'. It explicitly identifies this as 'Step 1' in a multi-step process, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Step 1' of authentication) and what to do with its output ('open in your browser to authenticate'). It distinguishes this from other authentication-related tools by positioning it as the initial step in the flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no ambiguity. Tools are well-organized into authentication, order management, and super order categories, with clear boundaries between similar tools like get_order_book vs get_super_order_book and cancel_order vs cancel_super_order_leg.
All tools follow a consistent verb_noun pattern with snake_case throughout. Authentication tools use verbs like start, complete, check, reset; order tools use get, place, modify, cancel; and naming is predictable across the entire set.
18 tools is slightly high but reasonable for a comprehensive trading API server. The count covers authentication, order placement, modification, cancellation, and status retrieval thoroughly without obvious bloat, though it's at the upper end of typical scoping.
The tool set provides complete coverage for the trading domain with full authentication flow, CRUD operations for orders and super orders, status retrieval, and trade tracking. There are no apparent gaps in the surface for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Institutional financial data with SEC filing citations, for every AI agent. OAuth 2.1.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/harshitdynamite/DhanMCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
