Distribución oficial: solo GitHub (
sahmk-sa/sahmk-mcp) y PyPI (sahmk-mcp). No instale desde forks de terceros.
Servidor MCP oficial de SAHMK para SAHMK — use datos del mercado saudí dentro de agentes de IA como Cursor y Claude Desktop.
Este MCP expone un conjunto seleccionado de herramientas de Sahmk para agentes de IA, de modo que los asistentes puedan consultar el mercado saudí en lenguaje natural.
Herramienta | Para qué usarla |
| Instantánea de un identificador de acción (símbolo, nombre o alias) |
| Compara varios identificadores de acciones en una sola llamada |
| Descubrimiento de directorio de empresas/símbolos con paginación |
| Resumen de |
| Principales movimientos por |
| Instantánea del rendimiento sectorial |
| Perfil de empresa y fundamentales |
| Estados financieros (plan Starter+) |
| Ratios financieros calculados (las funciones de Starter/Pro varían) |
| Comparación normalizada de ratios/métricas multi-símbolo (los límites de Starter/Pro varían) |
| Historial de dividendos y datos de rendimiento (plan Starter+) |
| Profundidad de cartera de órdenes (escalera de compra/venta, diferencial, desequilibrio) (restringido por permiso) |
| Impresiones de operaciones en vivo recientes / cinta (plan Pro+) |
| Resúmenes de eventos bursátiles generados por IA (plan Pro+) |
| Datos históricos OHLCV |
Related MCP server: equivault-mcp
Las entradas canónicas para las herramientas de cotización son identifier e identifiers.
Los alias heredados symbol y symbols todavía se aceptan por compatibilidad.
Prefiera las claves canónicas en prompts, llamadas a herramientas y plantillas de cliente.
La resolución está respaldada por backend/SDK (nombres, alias y símbolos); el MCP no mantiene su propio mapa de símbolos.
Use MCP para flujos de trabajo interactivos de agentes en herramientas como Cursor y Claude Desktop.
Use el SDK de Python para scripts, automatización, paneles, alertas, backtests y código de aplicación.
Repositorio del SDK: sahmk-sa/sahmk-python
Regístrate en sahmk.sa/developers
Ve a Panel de control → Claves de API → Crear clave
Copia tu clave (empieza con shmk_live_ o shmk_test_)
get_depth está restringido por permiso. Solicita acceso en tiempo real/profundidad desde el panel de desarrollador:
Solicitar acceso en tiempo real
SAHMK_API_KEY es obligatoria para todas las ejecuciones del servidor (Claude Desktop, Cursor y uso directo de CLI).
Configúrala en la configuración env de tu cliente MCP o expórtala antes de ejecutar sahmk-mcp.
Opcional: SAHMK_BASE_URL anula el host público predeterminado de la API de desarrollador.
La URL base REST predeterminada es https://api.sahmk.sa/api/v1/ (alineada con el SDK sahmk 0.16.0).https://app.sahmk.sa/api/v1/ sigue siendo un host de compatibilidad totalmente compatible: establece SAHMK_BASE_URL si lo necesitas:
export SAHMK_BASE_URL="https://app.sahmk.sa/api/v1"Las formas de las rutas no cambian (/api/v1/, /api/v2/, /ws/v1/). Las rutas del portal/panel (/api/developers/*) permanecen en app.sahmk.sa y este MCP no las utiliza.
pip install sahmk-mcpRequiere sahmk>=0.16.0 para la compatibilidad actual con MCP-SDK (host predeterminado api.sahmk.sa, profundidad de mercado, operaciones en vivo y herramientas de eventos).
Establece las claves de API mediante variables de entorno (SAHMK_API_KEY).
Nunca subas claves al control de versiones ni las compartas en registros.
Rota inmediatamente las claves expuestas desde tu panel de Sahmk.
Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key"
}
}
}
}Anulación opcional del host de compatibilidad (mismas rutas en app.sahmk.sa):
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key",
"SAHMK_BASE_URL": "https://app.sahmk.sa/api/v1"
}
}
}
}Añade a .cursor/mcp.json:
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key"
}
}
}
}Anulación opcional del host de compatibilidad:
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key",
"SAHMK_BASE_URL": "https://app.sahmk.sa/api/v1"
}
}
}
}export SAHMK_API_KEY="your_api_key"
sahmk-mcpget_market_summary.index: TASI o NOMU (el alias NOMUC se acepta y normaliza).
get_market_movers.type: gainers, losers, volume o value.
get_market_movers.limit: entero de 1 a 50.
get_quote.identifier (preferido): acepta símbolo numérico, nombre de empresa en árabe/inglés o alias conocido.
get_quote.symbol (alias heredado): aceptado por compatibilidad hacia atrás.
get_quotes.identifiers (preferido): máximo 50 identificadores por solicitud.
get_quotes.symbols (alias heredado): aceptado por compatibilidad hacia atrás.
get_financials.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
get_financials.period y get_financials.statement_period: si se proporcionan ambos, period tiene prioridad.
get_financials admite parámetros de paso opcionales: type, period, statement_period, history, metrics, result e include_partial.
La respuesta de get_financials se centra en bloques de estados y no incluye meta.
get_ratios.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
get_ratios.history: el valor predeterminado es latest.
get_ratios.period: el valor predeterminado es annual.
get_ratios.metrics: el valor predeterminado es core.
compare_symbols.symbols: lista de símbolos (preferida) o cadena separada por comas; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
compare_symbols.metrics: el valor predeterminado es core.
get_ratios y compare_symbols incluyen solo meta mínimo: period, metrics, warnings.
Las herramientas de análisis no exponen campos internos/backend como applied_profile, plan o diagnósticos de origen.
get_dividends.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
get_depth.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
get_depth.levels: entero opcional de 1 a 20 (el valor predeterminado del backend suele ser 5; el permiso puede limitarlo por debajo de la solicitud).
get_trades.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
get_trades.limit: entero opcional de 1 a 200 (el valor predeterminado del backend suele ser 50; primero los más recientes).
get_trades.events[].side: lado de la operación opcional, uno de buy, sell o null.
get_events.symbol: filtro opcional de símbolo exacto de la bolsa; omítelo para eventos recientes de todo el mercado.
get_events.limit: entero opcional de 1 a 100.
get_historical.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.
companies_list.market: TASI o NOMU (el alias NOMUC se acepta y normaliza).
companies_list.limit: entero mayor que 0.
companies_list.offset: entero mayor o igual que 0.
get_historical.interval: 1d, 1w, 1m, 30m o 60m.
Los identificadores ambiguos generan AMBIGUOUS_IDENTIFIER con orientación de reintento y candidatos cuando están disponibles.
Los identificadores no válidos y las solicitudes restringidas por plan devuelven el error de API subyacente.
Búsqueda en el directorio de empresas: companies_list(search="aramco")
Directorio de empresas por normalización de alias de mercado: companies_list(search="acwa", market="NOMUC")
Paginación del directorio de empresas: companies_list(search="bank", limit=50, offset=100)
Llamada de cotización única preferida: get_quote(identifier="أرامكو")
Llamada de cotización única heredada: get_quote(symbol="2222")
Llamada de cotización por lotes preferida: get_quotes(identifiers=["سبكيم", "كيان"])
Llamada de cotización por lotes heredada: get_quotes(symbols=["2222", "1120"])
Estados financieros por símbolo exacto: get_financials(symbol="1120")
Ratios financieros predeterminados: get_ratios(symbol="1120")
Ratios financieros avanzados: get_ratios(symbol="1120", history="5y", period="quarterly", metrics="extended")
Comparación de símbolos predeterminada: compare_symbols(symbols=["1120", "1180", "1010"])
Comparación de símbolos extendida: compare_symbols(symbols=["1120", "1180", "1010", "2222"], metrics="extended")
Dividendos por símbolo exacto: get_dividends(symbol="1120")
Profundidad de mercado por símbolo exacto: get_depth(symbol="2222")
Profundidad de mercado con niveles: get_depth(symbol="2222", levels=10)
Operaciones recientes por símbolo exacto: get_trades(symbol="2222")
Operaciones recientes con límite: get_trades(symbol="2222", limit=20)
El lado del evento de operaciones es aditivo y opcional: cada elemento de events[] puede incluir side = buy, sell o null.
Eventos de mercado recientes: get_events(limit=10)
Eventos para un símbolo: get_events(symbol="1120", limit=5)
Histórico por símbolo exacto: get_historical(symbol="1120", interval="1d")
Histórico con argumentos explícitos de rango de fechas diario: get_historical(symbol="1120", from_date="2026-01-01", to_date="2026-03-31", interval="1d")
Histórico intradía por símbolo exacto (restringido por plan según la clave de API): get_historical(symbol="1120", interval="60m")
Histórico intradía con argumentos explícitos de rango de fechas: get_historical(symbol="1120", from_date="2026-05-01", to_date="2026-05-31", interval="60m")
Usa companies_list primero para reducir los errores 404 de símbolos no válidos antes de las herramientas que solo usan símbolos.
Descubre candidatos por nombre o fragmento de símbolo:
companies_list(search="aramco")
companies_list(search="2222")
Opcionalmente, limita el descubrimiento por mercado:
companies_list(search="acwa", market="NOMUC") (NOMUC se normaliza a NOMU)
Elige un símbolo de results y luego llama:
get_quote(identifier="<symbol>")
get_financials(symbol="<symbol>")
get_dividends(symbol="<symbol>")
get_historical(symbol="<symbol>")
Para bucles de paginación, incrementa offset en limit hasta alcanzar total:
companies_list(search="bank", limit=100, offset=0)
companies_list(search="bank", limit=100, offset=100)
continúa hasta que offset >= total
Usuario: "سعر الراجحي" -> llama a get_quote(identifier="الراجحي").
Seguimiento: "قوائم الشركة" -> si el resultado anterior incluye resolved_instrument.symbol = "1120", reutilízalo y llama a get_financials(symbol="1120").
"Dame un resumen de TASI y el estado del mercado."
"Dame los principales movimientos del mercado TASI por ganadores."
"Dame los principales movimientos del mercado NOMU por valor."
"Muéstrame el rendimiento sectorial."
"Compara سابك, سبكيم y 2222 por cambio de precio y liquidez neta."
"Muéstrame el resumen de NOMU de hoy."
"Obtén los estados financieros de 2222."
"Obtén los dividendos de 2222."
"Muéstrame la cartera de órdenes / profundidad de mercado de 2222."
"Muéstrame las últimas operaciones de 2222."
"¿Cuáles son los últimos eventos bursátiles?"
"Obtén datos históricos de 1d para 1120 desde 2026-01-01 hasta 2026-03-31."
"Cuéntame sobre الراجحي y su sector."
Nota: get_financials y get_dividends requieren acceso a Sahmk API en el plan Starter o superior. Si no está disponible para la clave actual, el MCP devuelve el error subyacente de la API.
Nota: get_depth está restringido por derechos de acceso — solicitar acceso. get_trades y get_events requieren Pro+. Si no está disponible para la clave actual, el MCP muestra el error de la API.
Nota: los intervalos históricos intradía (30m, 60m) pueden estar limitados por plan. Si no están disponibles para la clave actual, el MCP muestra el error de la API (por ejemplo 403 PLAN_LIMIT).
0.8.1: aumenta el requisito mínimo del SDK sahmk a 0.16.0.
0.8.0: añade side opcional a los eventos de get_trades (buy/sell/null) con salida compatible con versiones anteriores para los payloads que lo omiten.
0.7.0: host público predeterminado de la API de desarrolladores → api.sahmk.sa (requiere sahmk>=0.15.0); app.sahmk.sa sigue siendo compatible mediante SAHMK_BASE_URL.
0.6.0: requiere sahmk>=0.14.0; añade get_trades para las impresiones recientes de operaciones en vivo (Pro+).
0.5.1: documenta el enlace de solicitud de acceso a la profundidad de mercado en el README.
0.5.0: requiere sahmk>=0.13.0; añade get_depth (escalera del libro de órdenes) y get_events (resúmenes de eventos con IA, Pro+).
0.4.7: elimina include_quality del contrato público de la herramienta get_financials, normaliza las entradas de dígitos arábigo-indios/ASCII equivalentes antes de las comprobaciones de conflicto de identificadores y mejora la UX del formulario de Glama con selectores de enumeración para opciones estables de ratio/período.
0.4.6: añade un respaldo de identificador basado en el SDK para get_company y las herramientas que priorizan el símbolo (get_financials, get_ratios, compare_symbols, get_dividends, get_historical) cuando las entradas de nombre/alias fallan en la búsqueda directa de símbolos.
0.4.5: alinea con sahmk>=0.11.0; amplía la compatibilidad de get_historical.interval a 30m/60m; documenta el comportamiento de limitación por plan para intradía.
0.4.4: documentación: aclara los canales de distribución oficiales (solo GitHub + PyPI)
0.4.3: Alinea el contrato de salida del MCP: sin meta en financials; el meta de analytics se limita a period, metrics y warnings.
0.4.2: Añade un respaldo de compatibilidad de nombres de métodos del SDK para analytics (get_ratios/ratios, compare_symbols/compare).
0.4.1: Requiere sahmk>=0.9.1 en la dependencia del paquete y en la comprobación de versión en tiempo de ejecución.
0.4.0: Añade herramientas de ratios y comparación de analytics; mejora los parámetros opcionales de financials.
MIT — ver LICENSE
Discover listed companies and symbols. Use this first to find/validate symbols before quote/company calls.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size (must be > 0). | |
| market | No | Optional market filter: 'TASI' or 'NOMU' (alias 'NOMUC' is accepted and normalized). | |
| offset | No | Pagination offset (must be >= 0). | |
| search | No | Optional text search across symbol/company names for discovery. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'Discover listed companies and symbols' without mentioning pagination, filtering behavior, or response format, which is insufficient for a list tool with 4 optional parameters.
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 delivering purpose and usage guidance without redundancy. Front-loaded with key action and context.
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?
Despite an output schema existing, the description lacks details on pagination and result structure. It provides minimal context for a tool with 4 optional parameters, but is not critically incomplete.
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 coverage is 100% with parameter descriptions already present. The description adds no extra meaning beyond the schema, so baseline score of 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 uses specific verb 'Discover' and resource 'listed companies and symbols', clearly distinguishing from siblings like get_company (single company) and get_quote (price 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?
Explicitly instructs to 'Use this first to find/validate symbols before quote/company calls', providing clear when-to-use context and implicit exclusion of other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare multiple Saudi-listed companies using normalized financial ratios and key metrics. Starter supports up to 3 symbols; Pro supports up to 10.
| Name | Required | Description | Default |
|---|---|---|---|
| metrics | No | Metrics profile, e.g. 'core' or 'extended'. Default 'core'. | core |
| symbols | Yes | Symbols to compare as a list (preferred) or comma-separated string. Starter supports up to 3 symbols; Pro supports up to 10. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not mention read-only nature, data freshness, or error behavior. Only plan limits are mentioned, which is minimal behavioral 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?
Two sentences, efficient, no wasted words.
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?
With output schema present, the description adequately covers purpose and parameter constraints. Could mention example or typical use case but is sufficient.
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 covers both parameters fully. Description repeats plan limits already in schema but adds no new parameter meaning.
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?
Clearly states the tool compares multiple Saudi-listed companies using normalized financial ratios. Mentions plan limitations, distinguishing it from single-company tools like get_ratios.
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?
No explicit guidance on when to use vs alternatives. Does not compare with siblings like get_ratios or get_quotes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a company profile for a Saudi stock, including sector, industry, fundamentals, valuation, technical indicators, and analyst consensus. Use this when the user asks about a company's profile, key metrics, or detailed information.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | Stock identifier (symbol, Arabic/English name, or alias), e.g. '2222', 'أرامكو'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, authentication requirements, or rate limits. The tool likely performs a safe read, but the description does not confirm this, leaving gaps.
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 no unnecessary words: first describes output, second provides usage guidance. It is front-loaded and efficiently uses space.
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?
An output schema exists (not shown), so return value documentation is covered. The description lists key data categories (sector, fundamentals, etc.), giving good context. Could optionally mention that it returns aggregate data, but overall complete.
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% coverage with a clear description for 'identifier' (symbol, name, alias). The tool description does not add extra parameter meaning beyond what the schema already provides, so 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 tool retrieves a company profile for a Saudi stock, listing included data types (sector, industry, fundamentals, etc.). It distinguishes itself from sibling tools like get_historical (historical data) or get_dividends (dividends only) by being comprehensive.
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?
Explicitly directs when to use: 'when the user asks about a company's profile, key metrics, or detailed information.' While it doesn't list alternatives for specific queries (e.g., dividends), the sibling list helps agents infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get market depth (order book) for a Saudi stock. Use this for bid/ask ladder, spread, imbalance, and liquidity at the top of book. Requires exact exchange symbol. Plan/entitlement-gated by the API.
| Name | Required | Description | Default |
|---|---|---|---|
| levels | No | Optional number of book levels to request (1-20). Backend default is 5; entitlement may return fewer levels than requested. | |
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '2222'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is 'Plan/entitlement-gated by the API' and that the symbol must be exact, but it does not explicitly confirm the operation is read-only or describe error behavior. The entitlement gating adds some value beyond the schema, which only mentions level reduction, not overall access.
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 compact and front-loaded with the core purpose. Each sentence adds value: purpose, use case, prerequisite, and gating. No wasted words.
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 output schema exists and both parameters are fully documented, the description covers the essential aspects: what it does, when to use it, and access restrictions. It does not address edge cases like symbol not found, but the schema's suggestion to use companies_list partially fills that gap. Overall, it is nearly complete for a 2-parameter read 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%, so the baseline is 3. The description repeats 'Requires exact exchange symbol' which is already in the schema, and does not add new meaning to either parameter. The levels parameter is adequately documented in 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 'Get market depth (order book) for a Saudi stock', providing a specific verb and resource. It distinguishes itself from siblings like get_quote (price) and get_trades (trades) by focusing on the order book.
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?
It explicitly says 'Use this for bid/ask ladder, spread, imbalance, and liquidity at the top of book' and mentions the prerequisite 'Requires exact exchange symbol'. It does not mention when not to use or name alternatives, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get company dividend history and yield data. Use this when the user asks for dividends or payout history. Requires exact exchange symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '1120'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions the requirement for an exact exchange symbol, but omits other important aspects like data freshness, error handling, or output 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 two sentences with essential information, no wasted words. It is front-loaded with the purpose and usage guidance.
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 dividend history tool with an output schema present, the description is minimally adequate. It lacks details on return format, pagination, or date scope, but the presence of the output schema mitigates the need for some of that.
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% coverage with a detailed description for the 'symbol' parameter. The tool description adds no additional parameter semantics, so 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 'Get company dividend history and yield data', specifying the verb and resource. It distinguishes from sibling tools like get_quote and get_financials, which focus on other 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 explicitly says 'Use this when the user asks for dividends or payout history', providing a clear when-to-use context. However, it does not mention when not to use or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-generated stock event summaries (Pro+ plan). Use this for recent corporate/news-style events with type, importance, and sentiment. Optionally filter by exact exchange symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional max number of events to return (1-100). Backend default is typically 20. | |
| symbol | No | Optional exact exchange symbol filter. Omit for market-wide recent events. Example: '1120'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden for disclosure. It adds useful context: events are AI-generated, require Pro+ plan, and can be filtered by exchange symbol. This goes beyond a bare 'get events' but could still mention pagination or defaults; however, the essential behaviors are clear.
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?
Three concise sentences, front-loaded with the primary purpose. Each sentence earns its place: what it does, when to use, and how to filter. No redundancy or fluff.
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 simplicity (2 optional params, output schema present) and the sibling set, the description is nearly complete. It covers purpose, use case, and optional filtering. It could add an explicit alternative or exclusion, but the provided information is sufficient for an agent to select and invoke the tool correctly.
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 coverage is 100%, so the baseline is 3. The description adds meaningful context for the symbol parameter by specifying 'exact exchange symbol' and explains that omitting it gives market-wide events. The limit parameter is left to the schema, but the description adequately supports the most common usage.
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 retrieves 'AI-generated stock event summaries' with specific attributes (type, importance, sentiment). It distinguishes itself from sibling quote and market data tools by focusing on corporate/news events.
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 says to use it 'for recent corporate/news-style events' and notes the Pro+ plan requirement. It does not explicitly list excluded use cases or alternatives, but the context and sibling tool names make it evident when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get company financial statements and key financial data. Use this for income statement, balance sheet, and cash flow requests. Requires exact exchange symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Optional financial view selector (e.g. statement family/profile returned by backend). | |
| period | No | Optional period selector: annual, quarterly, or auto. If both period and statement_period are provided, period takes precedence. | |
| result | No | Optional result shaping selector. Common values: series, latest, raw (backend-dependent). | |
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '1120'. | |
| history | No | Optional history window selector. Common values: latest, 1y, 3y, 5y, 10y, max (backend-dependent). | |
| metrics | No | Optional metrics profile selector. Common values: core, extended (backend-dependent). | |
| include_partial | No | Optionally include partial/incomplete statement periods when available. | |
| statement_period | No | Optional explicit statement period selector (annual, quarterly, or auto). Ignored when period is provided. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only mentions the symbol requirement and implicitly that the tool is a read operation, but does not describe error handling, rate limits, or the nature of the response. The lack of detail on optional parameters' behavior (e.g., what happens if type or metrics are omitted) 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 three sentences long and front-loaded with the core purpose. It is concise with no wasted words, but could benefit from additional structure (e.g., bullet points) to improve scanability.
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?
While an output schema exists (reducing the need to describe return values), the tool has 8 parameters with many optional combinations. The description provides only high-level purpose, leaving the agent to infer when to use specific parameters. Given the tool's complexity, the description is marginally adequate but not fully complete.
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, so the baseline is 3. The description adds minimal value beyond the schema, merely reinforcing that the symbol must be exact. It does not explain how the optional parameters (type, period, result, etc.) affect the output or provide context beyond their 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 tool retrieves financial statements (income, balance sheet, cash flow) and key financial data. It distinguishes itself from sibling tools like get_ratios and get_dividends by focusing on core statements, but does not explicitly contrast them, 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 specifies when to use this tool ('for income statement, balance sheet, and cash flow requests') and includes a key prerequisite ('Requires exact exchange symbol'). It also hints at fallback behavior (use companies_list for company names), but lacks explicit when-not-to-use guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical OHLCV price data for a Saudi stock over a date range. Use this when the user asks for past prices, price trends, or chart-style historical data.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '1120'. | |
| to_date | No | End date in YYYY-MM-DD format (default: today) | |
| interval | No | '1d' for daily, '1w' for weekly, '1m' for monthly, '30m' for 30-minute, or '60m' for 60-minute bars (default: '1d') | |
| from_date | No | Start date in YYYY-MM-DD format (default: 30 days ago) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the operation as data retrieval, implying read-only, but does not mention any behavioral aspects like authentication, rate limits, or error handling. This is adequate for a simple fetch operation, but lacks detail for full transparency.
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, no fluff, front-loaded with the core function and use case. Every sentence adds value.
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?
With output schema present and good schema parameter descriptions, the tool description is complete. It explains what the tool does and when to use it effectively for a data retrieval 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?
All four parameters have descriptions in the input schema (100% coverage). The tool-level description does not add additional meaning beyond the schema, meeting the baseline. The schema descriptions are sufficiently detailed (format, defaults, example).
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?
Description clearly states it gets historical OHLCV price data for a Saudi stock over a date range, and explicitly points to use cases like past prices, trends, or chart data. This distinguishes it from related tools like get_quote or get_financials.
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?
Description explicitly says to use when user asks for past prices or chart data. It doesn't specify when not to use or name alternatives, but the context is clear given sibling tools like get_quote for current prices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get market movers in one curated endpoint. Use this for top gainers, top losers, highest volume leaders, or highest value leaders. Returns a stable schema: type, index, count, items.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Mover type: 'gainers', 'losers', 'volume', or 'value'. | |
| index | No | Optional market index: 'TASI' or 'NOMU' (alias 'NOMUC' is accepted and normalized). | |
| limit | No | Optional number of results from 1 to 50. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It notes the output schema is stable and lists fields, but does not mention read-only nature, authentication needs, or rate limits. Adequate but not exhaustive.
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 extremely concise: two sentences. The first sentence states the tool's purpose, the second provides usage guidance and output schema. No wasted words.
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 presence of an output schema and 100% parameter coverage, the description is largely complete. It could optionally mention the default limit or index behavior, but the core information is present.
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 coverage is 100%, so baseline is 3. The description adds no parameter information beyond what the schema already provides (e.g., types, index values). No extra semantics.
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 retrieves market movers, a specific resource, and lists explicit use cases (top gainers, losers, volume, value leaders). It distinguishes itself from sibling tools which focus on individual symbols, sectors, or quotes.
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 says 'Use this for top gainers, top losers, highest volume leaders, or highest value leaders,' providing clear guidance on when to employ this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current Saudi market summary including TASI index level, change, market direction, and advancing/declining stock counts. Use this for questions about the overall market today.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional market index: 'TASI' or 'NOMU' (alias 'NOMUC' is accepted and normalized). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns summary data but does not explicitly state it is a read-only operation or address any side effects. The behavior is implied but not fully transparent.
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, front-loaded with the core purpose and components, followed by a usage guide. No waste; every sentence earns 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?
The description is complete for a simple summary tool, covering input and output components. An output schema exists, so return values are documented elsewhere. Could mention data freshness (e.g., real-time) but is adequate.
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 coverage is 100% and the schema already describes the optional 'index' parameter with valid values. The description adds no additional meaning beyond what the schema provides.
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 'Get' and the resource 'current Saudi market summary' with specific included components (TASI index level, change, direction, advancing/declining counts). It distinguishes from sibling tools like get_quote or get_company which focus on individual stocks.
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 says 'Use this for questions about the overall market today', providing clear context. It does not mention when not to use or explicitly name alternatives, but the use case is clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a real-time quote for a Saudi stock. Use this when the user asks for the current price, change, bid/ask, or trading activity of one stock.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | No | Legacy alias for identifier. Prefer 'identifier'. | |
| identifier | No | Stock identifier (preferred): symbol, Arabic/English name, or known alias, e.g. '2222', 'أرامكو', 'الراجحي'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It indicates a non-destructive read operation ('Get a real-time quote'), which is adequate, but it does not elaborate on any specific behavioral aspects such as data freshness or limitations.
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 no unnecessary words. The description is front-loaded and efficient.
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?
The description, combined with the existing output schema and sibling context, provides sufficient completeness for a simple one-stock quote tool. It could mention market hour restrictions, but it is not essential.
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 both parameters having detailed descriptions. The tool description adds little beyond the schema, which is acceptable. 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 tool gets a real-time quote for a Saudi stock and specifies the kind of information it returns (price, change, bid/ask, trading activity). It is sufficiently distinguishable from siblings like get_quotes (plural) and get_historical (time series).
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?
Explicitly advises when to use: when user asks for current price, change, bid/ask, or trading activity of one stock. This provides clear context for selection among siblings, though it does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get real-time quotes for multiple Saudi stocks in one call. Use this when the user wants to compare several stocks or asks for prices of more than one symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| symbols | No | Legacy alias for identifiers. Prefer 'identifiers'. | |
| identifiers | No | List of stock identifiers (preferred): symbol, Arabic/English name, or alias, up to 50 (e.g. ['2222', 'سابك']). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only mentions 'real-time' and 'in one call', but lacks details on data freshness limits, error handling, or that it supports up to 50 identifiers. The description is insufficient given the absence of annotations.
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 concise sentences, front-loaded with the main purpose. Every word adds value, and there is no extraneous information.
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?
An output schema exists, so return values need not be explained. However, the description omits key practical details like the maximum number of symbols (50) and potential differences between the two parameter options. It is adequate but not thorough.
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 already documents both parameters. The description adds no extra meaning beyond what the schema provides; it does not explain the distinction between 'identifiers' and 'symbols' or the accepted formats.
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 gets real-time quotes for multiple Saudi stocks, with a specific verb and resource. It implicitly distinguishes from 'get_quote' (single) and other sibling tools by emphasizing batch retrieval.
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 second sentence explicitly tells when to use it: 'when the user wants to compare several stocks or asks for prices of more than one symbol.' It provides clear context, though it doesn't mention explicit alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get calculated financial ratios for one Saudi-listed company. Starter returns latest annual core ratios; Pro supports history, quarterly, and extended metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Statement period for ratios. | annual |
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '1120'. | |
| history | No | History window for ratios. | latest |
| metrics | No | Metrics profile for ratios. | core |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It reveals tier-based limitations (Starter vs Pro), which parameters (history, period, metrics) are affected, and the scope of data (latest vs history, core vs extended). This is useful beyond the 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?
Two sentences with no wasted words. The first sentence states the primary purpose, and the second adds tier differentiation. Front-loaded and efficient.
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 presence of an output schema (not shown) which likely details the return structure, the description adequately covers the tool's purpose, scope, and tier constraints. Could mention that specific ratio types are not listed, but the schema handles that.
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 coverage is 100% with enums and descriptions for all four parameters. The description adds tier context but does not repeat or enhance param details. Baseline 3 is appropriate as the schema already 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 tool gets calculated financial ratios for one Saudi-listed company, specifying the region and constraint to a single company. It distinguishes between Starter and Pro tiers, indicating the scope of data available.
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 context about Starter vs Pro capabilities but does not explicitly guide when to use this tool over siblings like get_financials or get_historical. Usage is implied but not differentiated from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get sector performance for the Saudi market. Use this when the user asks for sector-level market moves or a sector snapshot. Returns a stable schema: index, count, items.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional market index: 'TASI' or 'NOMU' (alias 'NOMUC' is accepted and normalized). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral transparency. It mentions 'Returns a stable schema: index, count, items' and explains the normalization of 'NOMUC' alias, adding some context. However, it does not disclose whether the operation is read-only, what happens on errors, or describe the return structure in detail.
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 three sentences long, front-loading the purpose and usage. Every sentence adds value: the first states purpose, the second gives usage guidance, the third describes the return schema. No wasted words.
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 has only one optional parameter and an output schema (mentioned but not detailed), the description provides adequate context. However, it could briefly explain what 'index, count, items' represent to improve 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?
All parameters are documented in the schema (100% coverage). The description adds extra context beyond the schema, such as the normalization of 'NOMUC' to 'NOMU' and the stable return schema structure. This enhances understanding of parameter 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 tool's purpose: 'Get sector performance for the Saudi market.' It identifies the specific resource (sector performance) and action (get), distinguishing it from sibling tools like get_market_summary or get_market_movers which deal with broader market 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 explicitly says 'Use this when the user asks for sector-level market moves or a sector snapshot,' providing clear context for when to invoke this tool. While it does not list exclusions or alternatives, the guidance is sufficient for a straightforward tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent live trade prints for a Saudi stock (Pro+ plan). Use this for the trade tape: individual executions with price, quantity, value, and a short summary of recent activity. Requires exact exchange symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional max number of recent trade prints to return (1-200, newest first). Backend default is typically 50. | |
| symbol | Yes | Requires exact exchange symbol. If the user provides a company name, first use companies_list. If a previous tool result included resolved_instrument.symbol, reuse that symbol. Example: '2222'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral traits. It discloses an access restriction ('Pro+ plan'), the real-time nature ('live'), and a critical input constraint ('exact exchange symbol'). While it doesn't address rate limits or error handling, these are less critical for a read-only trade tape tool, and the description offers meaningful context beyond the 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 three direct sentences, front-loaded with the primary purpose and immediately followed by use-case and constraint. Every sentence earns its place, with no filler or repetition.
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?
The description covers the essential context: purpose, target audience (Saudi stocks), plan requirement, output composition (individual executions and summary), and a key usage prerequisite. An output schema exists, so detailed return fields are documented elsewhere. Minor gaps include no mention of rate limits or potential errors, but overall the description is sufficient for tool selection.
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 descriptions already provide full coverage for both parameters, including the exact-symbol requirement and an example ('2222'). The main description repeats 'Requires exact exchange symbol' but does not add new semantic meaning beyond the schema. Therefore, it does not elevate above the baseline.
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 function with a specific verb ('Get') and resource ('recent live trade prints for a Saudi stock'), and elaborates with 'trade tape: individual executions with price, quantity, value'. This distinguishes it from sibling tools like get_quote, which provides a single price snapshot, and get_depth, which might show order book depth.
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 says 'Use this for the trade tape', providing clear context for when to invoke this tool. It also highlights a key prerequisite ('Requires exact exchange symbol'), guiding the agent to resolve user-provided company names first. However, it does not mention alternatives or exclude cases where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.0get_depthget_eventsget_tradesv0.4.6get_financials8 fields changedInput schema / properties / history / descriptionPrevious value: -"Optional history window selector."New value: +"Optional history window selector. Common values: latest, 1y, 3y, 5y, 10y, max (backend-dependent)."Input schema / properties / include_qualityRemoved value: -{
- "anyOf": [
- {
- "type": "boolean"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optionally include quality indicators in response payload."
-}Input schema / properties / metrics / descriptionPrevious value: -"Optional metrics profile selector."New value: +"Optional metrics profile selector. Common values: core, extended (backend-dependent)."Input schema / properties / period / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "enum": [
+ "annual",
+ "quarterly",
+ "auto"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / period / descriptionPrevious value: -"Optional period selector. If both period and statement_period are provided, period takes precedence."New value: +"Optional period selector: annual, quarterly, or auto. If both period and statement_period are provided, period takes precedence."Input schema / properties / result / descriptionPrevious value: -"Optional result shaping selector."New value: +"Optional result shaping selector. Common values: series, latest, raw (backend-dependent)."Input schema / properties / statement_period / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "enum": [
+ "annual",
+ "quarterly",
+ "auto"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / statement_period / descriptionPrevious value: -"Optional explicit statement period selector. Ignored when period is provided."New value: +"Optional explicit statement period selector (annual, quarterly, or auto). Ignored when period is provided."get_ratios6 fields changedInput schema / properties / history / descriptionPrevious value: -"History window for ratios. Default 'latest'."New value: +"History window for ratios."Input schema / properties / history / enumAdded value: +[
+ "latest",
+ "3y",
+ "5y",
+ "10y",
+ "max"
+]Input schema / properties / metrics / descriptionPrevious value: -"Metrics profile, e.g. 'core' or 'extended'. Default 'core'."New value: +"Metrics profile for ratios."Input schema / properties / metrics / enumAdded value: +[
+ "core",
+ "extended"
+]Input schema / properties / period / descriptionPrevious value: -"Statement period for ratios, e.g. 'annual' or 'quarterly'. Default 'annual'."New value: +"Statement period for ratios."Input schema / properties / period / enumAdded value: +[
+ "annual",
+ "quarterly"
+]v0.4.5companies_listcompare_symbolsget_companyget_dividendsget_financialsget_historicalget_market_moversget_market_summaryget_quoteget_quotesget_ratiosget_sectorsScored across 15 tools
Most tools have clearly distinct purposes, with clear separation between quotes, market-level data, company fundamentals, ratios, and market depth. Minor overlap exists between get_company, get_financials, and get_ratios, but descriptions generally guide selection well.
The dominant pattern is get_<resource>, which is consistent and predictable. compare_symbols and companies_list break the pattern but are still readable and clear enough to not cause confusion.
At 15 tools, the set is well-scoped for a market-data server. Each tool covers a distinct data area such as quotes, movers, sectors, company profiles, financials, depth, trades, and historical data, so every tool earns its place.
The tool surface is comprehensive for read-only Saudi market data, covering discovery via companies_list, real-time quotes, market summaries, movers, sectors, company details, financials, ratios, dividends, order book depth, trades, events, and historical data. No major dead ends are apparent.
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official CoinMarketCap MCP server: real-time crypto prices, market cap, rankings and exchange data.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official MCP server for OmniDimension. Drive voice agents, dispatch calls, and run bulk campaigns.
