Click on "Deploy 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., "@dlp-invest-mcp What's my current position?"
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.
Servidor MCP que expõe as integrações da DLPInvest como tools para assistentes de IA compatíveis com MCP.
Antes de configurar o MCP, certifique-se de ter o uv instalado.
📖 Veja como instalar: https://docs.astral.sh/uv/getting-started/installation/
Related MCP server: Portfolio Tracker MCP Server
Copie o exemplo abaixo para o arquivo de configuração do seu IDE e substitua DLP-seu-token-aqui pelo seu token. Com o uv instalado, a IDE executa uvx dlp-invest-mcp ao iniciar o MCP; na primeira execução, o uvx baixa e executa o pacote automaticamente.
{
"mcpServers": {
"dlp-invest": {
"command": "uvx",
"args": ["dlp-invest-mcp"],
"env": {
"DLP_INVEST_API_TOKEN": "DLP-seu-token-aqui",
"DLP_INVEST_ACCESS_MODE": "read",
"UV_LINK_MODE": "copy"
}
}
}
}Read:
obter_operacoes
obter_carteira
obter_posicao
obter_rentabilidade
obter_extrato
obter_proventos
obter_ativos
obter_ativos_detalhes
obter_corretoras
obter_estrategias
obter_subestrategias
Write:
adicionar_operacoes
Pergunta | Descrição |
"Qual é minha posição atual na DLPInvest?" | Obtém a posição atual do usuário na carteira |
"Mostre minhas operações recentes" | Lista as operações realizadas na conta |
"Qual é a rentabilidade da minha carteira?" | Mostra o desempenho financeiro da carteira |
"Gere um extrato detalhado" | Produz um extrato financeiro completo |
"Quais corretoras estou usando?" | Lista as corretoras associadas à conta |
"O que são as minhas estratégias atuais?" | Mostra as estratégias definidas pelo usuário |
"Detalhe meu ativo mais valioso" | Fornece informações detalhadas sobre o ativo principal |
"Calcule meu retorno anualizado" | Calcula métricas de retorno financeiro |
"Mostre os subsistemas ativos" | Lista todos os subsistemas disponíveis |
"Qual é o valor total da minha carteira?" | Somatório de todos os ativos |
"Adicione uma nova operação" | adiciona operações via POST /operacoes |
Essas interações são apenas exemplos
DLP_INVEST_ACCESS_MODE=read - Modo somente-leitura: tools mutáveis não são expostas e requisições POST/PUT/DELETE são bloqueadas.
DLP_INVEST_ACCESS_MODE=write (padrão) - Habilita as tools mutáveis implementadas. Atualmente, adicionar_operacoes envia operações para POST /operacoes.
Os valores não diferenciam maiúsculas de minúsculas e espaços nas pontas são ignorados. Valores diferentes de read e write impedem a inicialização do servidor.
MIT — veja LICENSE.
Recupera detalhes de um ativo especifico pelo ticker.
Args:
ticker: Ticker do ativo (ex: PETR4).
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
| 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 the full burden. It only discloses the return envelope ('success' and either 'data' or 'error') and implies a read via 'Recupera'; it says nothing about auth, error conditions, or whether a missing ticker returns an error versus empty 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 purpose statement is front-loaded and the Args/Returns structure is easy to scan. The Returns line is largely redundant since an output schema exists, slightly diluting the concise intent.
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 low-complexity single-parameter read tool with an output schema, the description covers the essentials and need not restate return values. It falls short on usage routing and error behavior, leaving minor gaps an agent could trip on.
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 0%, so the description must compensate. It does define the single parameter ('Ticker do ativo') and supplies a concrete example ('PETR4'), which is useful, but adds no format rules, case sensitivity, or validation constraints.
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?
States a specific verb ('Recupera'), resource ('detalhes de um ativo') and lookup key ('pelo ticker'), making it distinguishable from the list-style sibling obter_ativos_tool. It does not, however, explicitly name the sibling it differs from, so the differentiation must be inferred.
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 says what the tool does but gives no when-to-use/when-not guidance and does not mention the alternative obter_ativos_tool or any prerequisite. An agent must guess that this is the single-asset counterpart to the asset list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todos os ativos disponiveis no sistema.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the full behavioral burden. It discloses only the return shape ('success' plus 'data' or 'error'), which is already covered by the output schema, and says nothing about read-only safety, pagination, volume of results, or failure conditions.
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 purpose is front-loaded in a single clear sentence. The trailing 'Returns' block is redundant given the output schema exists, but it is short enough not to be wasteful.
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 simple no-argument read tool with a declared output schema, the description covers the essentials of what it returns. It falls short only on routing the agent away from the near-identical obter_ativos_detalhes_tool, which is the one piece of context that matters most here.
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 takes zero parameters, so there is no parameter semantics to document; the schema is trivially complete at 100% coverage. Baseline 4 applies for a no-arg tool.
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 states a specific verb and resource ('Lista todos os ativos disponiveis no sistema'), so an agent knows this returns the full asset list. However, it never distinguishes itself from the closely-named sibling obter_ativos_detalhes_tool, leaving the boundary between 'list assets' and 'asset details' to inference.
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?
There is no when-to-use guidance, no prerequisites, and no alternatives named. The phrase 'no sistema' implies a full unfiltered listing, but the description never tells the agent when to prefer this over obter_ativos_detalhes_tool or the other obter_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera informacoes da carteira do usuario.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the full behavioral burden. 'Recupera' implies a read, but nothing is said about authentication, whether the result is scoped to the current user or account, or how much data is returned. The 'Returns: Dict with success and either data or error' line is about return shape, which the existing output schema already covers, so it adds little behavioral value.
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 short and front-loaded, stating the operation in the first sentence. The Returns block is redundant given an output schema exists, but it occupies only two lines and does not bury the main statement.
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 zero-parameter read tool with an output schema, return-value detail is not needed, so the main gap is conceptual scoping: with ten 'obter_*' siblings, the description should say what 'carteira' covers. It is minimally adequate but leaves the agent guessing about overlap with posicao/rentabilidade/extrato.
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 takes zero parameters, which is the baseline-4 case per the rubric. There is nothing for the description to disambiguate, and schema coverage is reported at 100%.
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?
It gives a clear verb+resource ('Recupera informacoes da carteira'), so the agent knows this is a read of portfolio data. However, 'carteira' overlaps heavily with ten siblings (obter_posicao_tool, obter_rentabilidade_tool, obter_extrato_tool, obter_ativos_tool), and the description never says what portfolio information distinguishes this tool. The purpose is identifiable but not discriminable from siblings.
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?
There is no when-to-use guidance, no prerequisite, and no mention of the many sibling tools. An agent facing obter_carteira_tool next to obter_posicao_tool and obter_rentabilidade_tool has no stated criterion for choosing this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todas as corretoras cadastradas.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the full behavioral burden. It mentions the return envelope with success/data/error, but that is already covered by the output schema; it does not disclose auth requirements, pagination, rate limits, or other operational traits for a read-only list 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, front-loaded with the action and resource. It contains no filler or redundant explanation, making it appropriately sized for a simple list tool.
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 zero-parameter read-only list tool with an output schema, the description is nearly complete. It states what is returned at a high level and the output schema handles return structure, though it could include brief usage context against sibling retrieval tools.
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 zero parameters and the schema is an empty object with 100% coverage. Per the baseline for zero-parameter tools, a 4 is appropriate; the description adds no parameter information because there is none to add.
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?
States a specific verb ('Lista') and resource ('corretoras cadastradas'), which distinguishes it from the other obter_* siblings that fetch operations, portfolio, positions, etc. The purpose is clear, though it largely restates the tool name without additional scoping detail.
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?
Provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools, prerequisites, or conditions for selection, leaving usage context entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todas as estrategias de investimento.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the full behavioral burden. It mentions a success/error envelope but says nothing about read-only safety, authentication needs, rate limits, ordering, or whether the list is exhaustive – all relevant for an agent calling a list endpoint with no schema-level safety hints.
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 first line is a single, front-loaded purpose statement with no filler, and the return-contract note follows. It is appropriate in size, though the return block is partially redundant given an output schema exists.
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 an output schema present, the return-value explanation is not strictly required, leaving the description adequate for a no-param list tool. Still, the total absence of guidance on sibling selection and read-only behavior means an agent lacks the context needed to choose it confidently among ten similar tools.
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?
There are zero parameters, so the baseline is 4. The description correctly adds no parameter details because none exist; no compensation is needed.
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?
States the verb 'Lista' and the resource 'estrategias de investimento', which is clear. However, with ten sibling tools all prefixed 'obter_' and retrieving different investment data lists, the description does not differentiate what an 'estrategia' is versus 'subestrategias' or 'operacoes', leaving an agent to infer scope from the name alone.
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 indication of when to use this tool versus the many siblings like obter_subestrategias_tool or obter_operacoes_tool. There are no exclusions, prerequisites, or routing hints, so an agent must guess based solely on the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera o extrato financeiro da carteira.
Args:
carteira: ID ou nome da carteira.
data_inicial: Data inicial no formato YYYY-MM-DD.
data_final: Data final no formato YYYY-MM-DD.
limite: Maximo de resultados.
offset: Paginacao.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| limite | No | ||
| offset | No | ||
| carteira | No | ||
| data_final | No | ||
| data_inicial | No |
| 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 the full burden. It discloses the return envelope (success plus data or error), but says nothing about read-only nature, permission requirements, rate limits, or the effect of the defaulted limite/offset values on result volume.
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 Args/Returns docstring structure is compact and front-loaded, with the purpose stated in the first line and no filler. It is appropriately sized for a five-parameter retrieval tool.
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 the brief Returns note is adequate. Still missing are the behavioral details an agent needs for a portfolio statement call: whether date range is inclusive, whether omitting carteira aggregates all portfolios, and how pagination terminates.
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 0%, so the description is the only source of parameter meaning; it documents all five params including the YYYY-MM-DD date format and that carteira accepts an ID or name. It does not explain that every parameter is optional/nullable or what the defaults (limite=100, offset=0) imply, so it only partially compensates for the coverage gap.
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?
States a specific verb and resource ("Recupera o extrato financeiro da carteira"), which is clear enough to distinguish from obter_carteira_tool or obter_rentabilidade_tool. However, it never contrasts itself with the closest sibling, obter_operacoes_tool, so an agent must guess whether "extrato" and "operacoes" overlap.
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?
There is no guidance on when to use this tool versus alternatives such as obter_operacoes_tool or obter_posicao_tool, and no prerequisites or exclusions are stated. The agent must infer the use case from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera a lista de operacoes do sistema DLPInvest.
Args:
carteira: ID ou nome da carteira para filtrar.
status: Status da operacao (aberta, fechada, pendente).
data_inicial: Data inicial no formato YYYY-MM-DD.
data_final: Data final no formato YYYY-MM-DD.
limite: Maximo de resultados a retornar.
offset: Paginacao (quantidade de itens a pular).
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| limite | No | ||
| offset | No | ||
| status | No | ||
| carteira | No | ||
| data_final | No | ||
| data_inicial | No |
| 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 the burden. It does disclose the return contract ('success' plus 'data' or 'error') and indicates pagination via offset, which is genuine behavioral context. It stops short of stating permissions, result caps, or default behavior beyond the schema defaults.
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?
Uses a clean Args/Returns structure and leads with the purpose sentence before parameters. Well-sized with no filler, though the Args section is somewhat verbose relative to the sparse top-line description.
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?
Six parameters are all documented and the return shape is described even though an output schema exists. With no annotations, the safety profile is unaddressed, but the description is largely sufficient for a filtered-list 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 0%, so the description must compensate, and it does: it labels all six parameters, gives accepted status values (aberta, fechada, pendente), specifies the date format (YYYY-MM-DD), and explains offset as items to skip. It could be slightly stronger on how carteira accepts either ID or name 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?
States a clear verb ('Recupera') and resource ('lista de operacoes do sistema DLPInvest'), so the agent knows what it returns. However, it does not differentiate from close siblings like obter_extrato_tool or obter_posicao_tool, which could plausibly retrieve overlapping transaction 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?
No guidance on when to use this tool versus the many sibling listing tools, and no exclusions or prerequisites. The description merely enumerates filter parameters without saying what scenario selects this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera a posicao atual dos ativos na carteira.
Args:
carteira: ID ou nome da carteira.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| carteira | No |
| 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 the full burden. 'Recupera' implies a read-only operation and it discloses the return shape (success with data or error), but it says nothing about permissions, scoping, or whether an empty/missing carteira changes 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 core purpose sentence is front-loaded and the Args/Returns block is compact and free of filler. Nothing is padded, though the docstring-style framing adds minor overhead for a one-parameter tool.
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 an output schema and only one optional parameter, the description does not need to explain return values, and it covers the parameter adequately. The remaining gap is the absence of any disambiguation from the many near-identical sibling tools, which is the main thing an agent needs here.
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 0% and the single parameter is optional with no description in the schema. The description compensates by documenting that 'carteira' accepts an ID or a name, which is meaningfully more than the bare string type 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?
States a clear verb+resource: 'Recupera a posicao atual dos ativos na carteira.' An agent knows it returns asset positions, but nothing distinguishes it from closely-named siblings like obter_carteira_tool or obter_ativos_tool.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With ten sibling 'obter_*' tools covering adjacent data, the agent is left to guess when this one is the right call versus obter_carteira_tool or obter_ativos_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera os proventos (dividendos, JCP, etc.) recebidos.
Args:
carteira: ID ou nome da carteira.
data_inicial: Data inicial no formato YYYY-MM-DD.
data_final: Data final no formato YYYY-MM-DD.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| carteira | No | ||
| data_final | No | ||
| data_inicial | No |
| 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 the full burden. It discloses the return contract (a dict with 'success' and either 'data' or 'error'), which is useful, but says nothing about permissions, pagination, or behavior on missing/empty data for a read 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?
Front-loads the purpose, then cleanly separates Args and Returns. No wasted sentences; the structure is easy to scan despite being in Portuguese.
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 needn't be explained, and parameters are covered. However, with no annotations and no usage guidance, the definition leaves the agent without routing context among many similar siblings.
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 0%, so the description must compensate, and it does: it documents all three parameters (carteira as ID or name, data_inicial/data_final) and gives the explicit YYYY-MM-DD date format that the schema lacks.
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?
States a specific verb (Recupera) and resource (proventos: dividendos, JCP), with examples clarifying the domain. This distinguishes it from siblings like obter_operacoes_tool or obter_posicao_tool by resource, though it never names an alternative explicitly.
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?
There is no guidance on when to use this tool versus the ten sibling 'obter_*' tools, nor any exclusions or prerequisites. The agent must infer usage from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera a rentabilidade da carteira em um periodo.
Args:
carteira: ID ou nome da carteira.
data_inicial: Data inicial no formato YYYY-MM-DD.
data_final: Data final no formato YYYY-MM-DD.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
| carteira | No | ||
| data_final | No | ||
| data_inicial | No |
| 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, and it does disclose the return shape ('Dict with success and either data or error'), which signals a read operation. However, it says nothing about permissions, what happens when optional parameters are omitted, or rate limits, so significant behavioral context is still missing.
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?
Purpose is front-loaded in the first sentence, followed by structured Args and Returns sections. The docstring boilerplate is slightly verbose but each line carries parameter or return information, so nothing is wasted.
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 the return description need not be exhaustive, and all three parameters are covered. The main gap is that the meaning of the optional/null defaults and their effect on results is left unexplained.
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 0%, so the description must compensate, and it documents all three parameters with their meaning and expected formats (carteira as ID or name, dates as YYYY-MM-DD). This adds real value over the bare schema, though it doesn't explain the all-optional/null defaults.
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?
States a specific verb+resource ('Recupera a rentabilidade da carteira') scoped to a period, which is clear and distinct in resource from siblings like obter_posicao and obter_extrato. It does not, however, explicitly differentiate itself from those siblings or clarify the relationship to the other obter_* tools.
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 gives no indication of when to use this tool versus the many sibling retrieval tools, nor any prerequisites or exclusions. The only implicit guidance is 'em um periodo', which hints at time-bounded use but stops short of telling the agent when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todas as subestrategias de investimento.
Returns:
Dict with ``success`` and either ``data`` or ``error``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the full behavioral burden. It mentions the return shape but does not disclose whether the operation is read-only, whether it requires authentication, whether results are paginated, or any other behavioral trait beyond the obvious listing action.
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 short and front-loads the purpose. The additional 'Returns' line is unnecessary because an output schema exists, but it does not make the description bloated.
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 no-parameter list operation with an output schema, the description covers the core purpose. However, it omits usage guidance relative to sibling tools and provides no behavioral context in the absence of annotations, leaving clear gaps.
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 takes zero parameters, so there are no parameter semantics to explain. The schema description coverage is 100%, and a baseline of 4 is appropriate for a parameterless tool.
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 states a clear verb and resource: 'Lista todas as subestrategias de investimento' (lists all investment substrategies). It distinguishes itself from generic strategy tools by naming 'subestrategias', though it does not explicitly contrast with the sibling 'obter_estrategias_tool'.
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?
There is no guidance on when to use this tool versus the many sibling getter tools. It neither states prerequisites nor explicitly says when not to use it, leaving the agent to infer context from the name alone.
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.1.0obter_ativos_detalhes_toolobter_ativos_toolobter_carteira_toolobter_corretoras_toolobter_estrategias_toolobter_extrato_toolobter_operacoes_toolobter_posicao_toolobter_proventos_toolobter_rentabilidade_toolobter_subestrategias_toolScored across 11 tools
Each tool targets a distinct resource: operations, portfolio, positions, profitability, statement, dividends, assets, asset details, brokers, strategies, and sub-strategies. Descriptions clarify boundaries, and there is no apparent overlap (e.g., operations vs. statement are differentiated by filters and purpose).
All tools follow the exact same pattern: obter_<resource>_tool in snake_case. The convention is fully consistent across the entire set.
Eleven tools are well within the ideal range (3–15) and each maps to a meaningful read operation for an investment data retrieval server. No tool feels redundant or out of place.
The surface covers core read-only needs: portfolio, positions, operations, profitability, statement, dividends, assets, brokers, strategies, and sub-strategies. Minor gaps exist (e.g., no write operations, no asset price history), but these may be intentional for a read-only reporting server.
Portfolio analytics + US-equity market research for AI clients. ChatGPT deep-research compat.
Agentic brokerage access to a US brokerage account: quotes, orders, positions, cash and documents.
Connect your portfolio to Claude, ChatGPT, or Codex to analyze it and make smarter investments.
Research US-listed companies and funds with the StockPortfolio.pro MCP server. Tools cover SEC filing-grounded financials, filing timelines, company comparisons, watchlist screens, fund profiles, and cited filing questions. Filed figures include their fiscal period and EDGAR source URL; missing filing data is returned as null. Public tools work without authentication; optional API-key or OAuth access is supported. US-listed, USD-reporting companies only. Keyless access includes 3 free AI questions per rolling 30-day window. To get more now, choose the Dev plan ($19.99/month, 200 credits) at https://www.stockportfolio.pro/register?plan=dev, then follow https://www.stockportfolio.pro/docs/api-mcp to connect with OAuth or an API key. Or wait for the free allowance to renew.
