This server connects to your Hotmart account, enabling you to manage sales, subscriptions, products, coupons, events, and members area through natural language commands and visual dashboards.
💰 Sales
List sales history, view summaries, participants, price details, and commissions (producer, co-producer, affiliate)
Refund a sale by transaction code ⚠️ (irreversible)
Visual apps: sales dashboard (revenue cards, daily chart, payment type breakdown), sales breakdown (top products/buyers), commissions dashboard
🔁 Subscriptions
List subscriptions, transactions, summaries, and subscriber purchase history
Cancel (single or batch) ⚠️, reactivate (single or batch), and change billing due day
Generate or preview negotiation proposals for delinquent subscribers (boleto/PIX installment plans)
Visual apps: subscriptions health dashboard, churn analyzer, subscriber 360 view
📦 Products
List products, their offers (prices/discounts), and subscription plans
Visual app: product catalog dashboard
🎟️ Coupons
List, create, and delete coupons for specific products
Visual app: coupon manager (validity, discount, usage)
🎓 Members Area (Club)
List modules, pages, and students; retrieve student progress
Visual apps: module analytics dashboard, students overview (engagement, progress ranking)
🎫 Events (ETICKET only)
Get event info and list participants (filterable by lot, ticket type, status, check-in)
Visual app: event dashboard with participant table and lot breakdown
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., "@hotmart-mcp cria um cupom de 20% pro produto X"
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.
Connect Claude (or any MCP client) to your Hotmart account. Sales, subscriptions, members area, products, coupons.
pip install git+https://github.com/thaleslaray/hotmart-mcp.gitRelated MCP server: cobroya
Get your credentials at developers.hotmart.com → create app → copy Client ID, Client Secret and Basic.
Paste them into .mcp.json (or claude_desktop_config.json):
{
"mcpServers": {
"hotmart": {
"command": "hotmart-mcp",
"env": {
"HOTMART_CLIENT_ID": "cole_aqui",
"HOTMART_CLIENT_SECRET": "cole_aqui",
"HOTMART_BASIC_AUTH": "cole_aqui"
}
}
}
}Restart Claude. Done.
Ask in plain English:
"How much did I sell last month?"
"List the subscriptions that were canceled this week"
"Create a 20% coupon for product X"
"Who watched more than 80% of module Y?"
"Refund sale HP12345"
Open an issue.
MIT
Batch Cancel Subscriptions. Use this for multiple subscriber_codes at once. For a single one, prefer hotmart_subscription_cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | List of subscriber codess. Pass a JSON array of strings, e.g. `['ABC123XY', 'DEF456ZW']`. | |
| send_mail | No | Enviar e-mail de notificação aos assinantes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description conveys destructive action (cancel). Lacks details on side effects like send_mail behavior or partial success handling, which would improve 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 redundant information, front-loaded with the main action.
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?
Sufficient for a simple batch cancel tool with output schema present. Missing info on error handling or send_mail impact, but not critical for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value with an example format for subscriber_code (JSON array of strings). send_mail is not elaborated, but the schema provides a Portuguese description.
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?
Clear verb 'batch cancel subscriptions' with resource specified. Explicitly distinguishes from sibling 'hotmart_subscription_cancel' for single cancellations.
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?
States when to use (multiple subscriber_codes) and when not (single one), directing to the appropriate sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch Reactivate Subscriptions. Use this for multiple subscriber_codes at once. For a single one, prefer hotmart_subscription_reactivate.
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | List of subscriber codess. Pass a JSON array of strings, e.g. `['ABC123XY', 'DEF456ZW']`. | |
| charge | No | Cobrar imediatamente |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Batch Reactivate Subscriptions' without disclosing behavioral traits like idempotency, partial failure handling, or authentication requirements. The charge parameter is mentioned briefly (Cobrar imediatamente) but not elaborated.
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, very concise and front-loaded with the core purpose. Every word 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?
With an output schema present, return values are handled. However, for a batch operation, more context about behavior (e.g., partial success, errors) would be beneficial. The description is minimal but sufficient for a simple batch 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 coverage is 100%, and the description adds little beyond restating that it's for multiple subscriber_codes. The schema already describes the parameters adequately, so the description does not significantly enhance 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?
The description clearly states the action (Batch Reactivate), the resource (Subscriptions), and specifically distinguishes from the sibling tool `hotmart_subscription_reactivate` for single subscriptions.
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 states when to use this tool (multiple subscriber_codes) and when not to (single code), and names the preferred alternative, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Análise de churn — cancelamentos por período + tendência.
LineChart cancelamentos no tempo + DataTable de recentes. Use pra 'análise de churn', 'cancelamentos da semana', 'taxa de cancelamento'.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | No | Optional product_id filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns a line chart and data table of recent cancellations, which is helpful. However, it does not detail any behavioral traits such as data limits, default time periods, or authentication requirements, leaving some gaps for an agent.
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 followed by usage examples. It is front-loaded with the core purpose and immediately actionable. No extraneous information, 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?
Given the low complexity (single optional parameter, no output schema), the description provides enough context: purpose, output format (line chart + data table), and example uses. It might benefit from specifying default behavior (e.g., time range), but it is sufficient for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the only parameter ('Optional product_id filter.'). The tool description does not add further parameter meaning, so it meets the baseline of 3 as the schema already suffices.
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: 'Análise de churn — cancelamentos por período + tendência' (churn analysis — cancellations by period + trend). It explicitly mentions the output (LineChart and DataTable) and distinguishes it from sibling tools by focusing on churn analysis, which is not covered by other tools like sales dashboards or subscription lists.
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 clear usage context by listing example queries: 'Use pra 'análise de churn', 'cancelamentos da semana', 'taxa de cancelamento''. This tells the user when to invoke the tool. However, it lacks explicit instructions on when not to use it or alternative tools for different scenarios, which would have made it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Painel de comissões — total a pagar/receber por afiliado.
DataTable com afiliado/papel/valor + Metric de total. Use pra 'comissões do mês', 'quanto pagar pros afiliados', 'settlement'.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date. Unix timestamp in milliseconds. | |
| end_date | No | End date. Unix timestamp in milliseconds. | |
| commission_as | No | PRODUCER | COPRODUCER | AFFILIATE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose behavioral traits like read-only, destructive actions, rate limits, or auth requirements. Only implies it's a dashboard, likely read-only, but not explicit.
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?
Description is short and front-loaded, but second sentence is fragmented. Overall 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?
Despite no output schema, description gives high-level output structure (DataTable and Metric) and use cases. Missing details like return format, pagination, or behavior with null parameters, which are left to the schema. 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?
Schema covers all parameters with 100% description coverage. Description does not add additional semantic meaning beyond what schema already provides (dates as Unix timestamps, commission_as values). 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?
Description clearly states it's a commissions dashboard showing totals to pay/receive per affiliate, with DataTable and metric. It distinguishes from many sibling tools by focusing on commissions, but does not explicitly differentiate from similar tools like hotmart_sales_commissions_list.
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 specific use cases: 'comissões do mês', 'quanto pagar pros afiliados', 'settlement'. Gives context for when to use, but no explicit when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create Coupon. Example: hotmart_coupon_create(product_id=12345).
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID | |
| code | Yes | Coupon code (máximo 25 caracteres) | |
| discount | Yes | Discount fraction (between 0 and 0.99 exclusive). **Fraction between 0 and 1** (NOT percent). Ex: `0.25` = 25% off. Pass `0.10` for 10%, NOT `10`. | |
| start_date | No | Validity start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | Data de fim de validade. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| affiliate | No | ID do afiliado | |
| offer_ids | No | IDs das ofertas aplicáveis. Pass a JSON array of integers, e.g. `[12345, 67890]`. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 such as side effects, idempotency, required permissions, or error conditions. The example only shows a basic call.
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 short (one sentence plus an example) but lacks critical information. Conciseness should not sacrifice completeness; here it is under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, output schema present), the description is too minimal. It does not explain return value behavior, error handling, or whether the coupon is created immediately.
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 provides detailed descriptions for all 7 parameters (100% coverage), including specifics like discount fraction and date format. The description adds no additional meaning beyond 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 states 'Create Coupon' which is a clear verb+resource, but it does not differentiate from sibling tools like hotmart_coupon_delete or hotmart_coupons_list. The example is generic and does not clarify unique purpose.
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 alternatives (e.g., when to use this vs a different coupon creation method). No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete Coupon. Example: hotmart_coupon_delete(coupon_id=12345).
| Name | Required | Description | Default |
|---|---|---|---|
| coupon_id | Yes | Coupon ID |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It only says 'Delete Coupon' without noting permanence, permissions, or side effects on associated 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?
Extremely concise: one sentence and an example. No wasted words, though slightly more context could help.
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 low complexity (one parameter, output schema exists), the description covers the basics but misses safety context like deletion irreversibility.
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% for the single parameter 'coupon_id'. The example usage adds minimal value beyond the schema's description.
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 explicitly states 'Delete Coupon' with a concrete example, making the action and resource clear. It distinguishes from sibling tools like hotmart_coupon_create and hotmart_coupons_list.
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 vs alternatives, no prerequisites or consequences mentioned. Only an example call is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Painel de cupons de um produto — listagem com validade/desconto/usos.
DataTable de cupons + Metric. Use pra 'listar cupons do produto X',
'ver cupons ativos', 'gerenciar cupons'. Pra CRIAR cupom use a tool
hotmart_coupon_create direta.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes a view (DataTable + Metric), but the phrase 'gerenciar cupons' hints at possible management actions without clarification. The absence of destructive hints is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. It includes a helpful redirect to the create tool. Minor improvement could be structuring the example uses more clearly.
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 (one parameter, no output schema), the description provides sufficient context for a panel/management view. It references the create tool appropriately. However, it could be more explicit about the difference from the list tool and about possible mutation actions.
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 a single parameter 'product_id' having a basic description. The description adds only context that it is 'de um produto' (of a product), which does not significantly enhance semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a coupon panel listing coupons with validity/discount/uses, and provides example use cases. It differentiates from the create tool but does not distinguish from the sibling hotmart_coupons_list.
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 tells when to use it (to list/manage coupons) and directs users to another tool for creation. It does not provide exclusions for when not to use it versus the list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Coupons. Example: hotmart_coupons_list(product_id=12345).
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID | |
| code | No | Coupon code | |
| page_token | No | Pagination token for the next page | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden; it only states 'Get Coupons' and gives an example, with no mention of read-only nature, side effects, rate limits, or pagination 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?
Extremely concise (one sentence plus example) but lacks structure; no front-loading of key info like purpose or return type. Not verbose but also not well-organized.
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 having an output schema and pagination parameter (page_token), the description provides no context about return values or how to handle pagination, leaving gaps for the 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?
Schema description coverage is 100%, so baseline is 3. The description adds nothing meaningful beyond the schema (example only shows product_id).
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 'Get Coupons' with a verb and resource, and is distinct from sibling tools like hotmart_coupon_create and hotmart_coupon_delete.
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 alternatives (e.g., hotmart_coupon_create for creation) or any context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Painel de evento — info + lista de participantes + breakdown lotes.
Card com info + DataTable participantes + PieChart por lote. Funciona apenas pra produtos formato ETICKET (não ONLINE_EVENT). Use pra 'ver dados do evento X', 'quem comprou ingresso pro evento'.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event ID (integer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes the visual components (card, DataTable, PieChart) and the product format constraint, but does not explicitly state read-only behavior, response structure, or error handling. The dashboard context implies safe operation, but without annotations or explicit disclosure, the transparency is adequate but not comprehensive.
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, using three short sentences: a title listing components, a line listing the visual elements, and a line with constraints and usage examples. Every sentence is informative and necessary. The structure is front-loaded, making the purpose immediately clear. There is no superfluous content.
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 dashboard app with one parameter and no output schema, the description sufficiently covers its functionality: it provides an info card, participant DataTable, and lot breakdown PieChart. It identifies the constraint of ETICKET-only. While it could mention error cases (e.g., invalid event ID), the description is complete enough for an agent to decide to invoke it. The sibling tools cover more granular data, so the dashboard's scope is clear.
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% cover. The description does not add additional meaning beyond what the schema provides for the single 'event_id' parameter. The schema already states it's an integer event ID. Given the high coverage, a baseline score of 3 is appropriate; the description adds no extra semantic guidance.
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 it is an event dashboard with info, participant list, and breakdown by lots. It specifies it works only for ETICKET products (not ONLINE_EVENT), effectively distinguishing it from sibling tools like hotmart_event_info_get and hotmart_event_participants_list. The provided example queries 'ver dados do evento X' and 'quem comprou ingresso pro evento' reinforce its specific purpose.
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 limits usage to ETICKET format and provides example use cases. It excludes ONLINE_EVENT, giving clear when-not-to-use guidance. However, it does not name alternative sibling tools for other event formats, which would have made it more complete. The examples are helpful for an agent to match user queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Event Info. Example: hotmart_event_info_get(event_id=12345).
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event ID | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as read-only nature, authentication requirements, rate limits, or side effects. The example implies a simple query, but behavioral context is 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?
The description is short with two sentences, but the first sentence is too terse ('Event Info') and the example is not structured to front-load key information. It is concise but lacks substance.
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 large number of sibling tools related to events, the description does not explain how this tool differs or what type of event info it returns. The presence of an output schema is not leveraged in the description to provide completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already defines both parameters. The description adds an example illustrating the required event_id parameter, which is helpful but does not provide significant new meaning beyond 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 'Event Info' is vague and lacks a specific verb or resource. The example shows usage but does not differentiate from sibling tools like hotmart_event_dashboard_app or hotmart_event_participants_list. The purpose is unclear beyond being about event information.
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 is provided on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or scenarios for use, leaving the agent to infer usage 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.
Event Participants. Example: hotmart_event_participants_list(event_id=12345, max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event ID | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| buyer_email | No | Buyer email | |
| participant_email | No | Email do participante | |
| last_update | No | Última atualização. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| id_lot | No | ID do lote | |
| ticket_status | No | Status do ingresso. | |
| ticket_type | No | Tipo do ingresso. Allowed values: 'PAID', 'FREE', 'ALL' | |
| checkin_status | No | Status do check-in. | |
| id_eticket | No | ID do e-ticket | |
| ticket_qr_code | No | QR code do ingresso. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as read-only nature, pagination behavior, authentication requirements, or side effects. The brief description leaves the agent uninformed about important operational details.
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 very concise with one sentence and an example. It is front-loaded with the resource name. However, it could be more structured by including a clear purpose 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?
Despite the high number of parameters (13) and the existence of an output schema, the description provides no context about return values, pagination logic, or how parameters interact. The agent lacks sufficient information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 13 parameters (100% coverage), so the description does not need to add much. However, the description only includes an example call and does not add meaning beyond the schema, which is adequate given the high schema coverage.
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 'Event Participants' and the example call clearly indicate the tool lists participants for a given event. The tool name includes 'list', so the purpose is clear, though the description lacks an explicit verb like 'List'.
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 is provided on when to use this tool versus alternatives like 'hotmart_sales_participants_list' or 'hotmart_subscriptions_list'. There is no differentiation of use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Análise por módulo da área de membros — qty aulas por módulo.
BarChart aulas/módulo + DataTable. Use pra 'estrutura da área de membros', 'quantas aulas por módulo'.
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | Members area subdomain. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the tool outputs a bar chart and data table, implying a read-only operation. However, it does not explicitly confirm it is read-only, mention authorization requirements, rate limits, or any side effects. For a tool with no annotations, the description could be more explicit about safety.
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 short sentences that front-load the main purpose and output format. Every word adds value; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter, no output schema, and no annotations, the description adequately covers the core functionality: it explains what the tool does, the input needed, and the output format. However, it could mention if the data is aggregated or real-time, and it lacks any note about permissions or limitations relative to other analytics 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 input schema has one parameter (subdomain) with description 'Members area subdomain.' The tool description adds no extra meaning beyond what the schema already provides, such as acceptable formats or examples. Since schema coverage is 100%, the baseline score is 3; the description does not elevate it.
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: 'Análise por módulo da área de membros — qty aulas por módulo.' It specifies the resource (modules), the metric (number of lessons), and the output format (bar chart + data table). This distinguishes it from sibling analytics tools like hotmart_churn_analyzer_app or hotmart_commissions_dashboard_app, which focus on other metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use pra 'estrutura da área de membros', 'quantas aulas por módulo'.' However, it does not mention when not to use this tool or suggest alternatives among the many sibling tools, which would be helpful given the large number of analytics options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Pages. Example: hotmart_module_pages_list(module_id='…'). Requires module_id from hotmart_modules_list first.
| Name | Required | Description | Default |
|---|---|---|---|
| module_id | Yes | Module ID | |
| subdomain | Yes | Members area subdomain (the slug from `hotmart.com/club/<slug>` URL) | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. However, it only states 'Get Pages' which implies a read operation, but does not confirm read-only behavior, mention side effects, pagination, or rate limits. The description fails to add transparency beyond the basic 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 very short (one sentence plus an example), which is concise but at the expense of completeness. It front-loads the purpose but is too minimal to fully inform the agent.
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 3 parameters (2 required) and an output schema, the description is insufficient. It does not explain what 'pages' are, how subdomain is used, or how results are structured. The output schema exists but the description should still provide context about the tool's function in the module workflow.
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 input schema already describes all parameters. The description adds only an example using module_id, which is helpful but does not provide additional meaning for subdomain or select. It adds marginal value over 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 'Get Pages' is vague and does not specify what kind of pages (e.g., module content pages). The example provides some context but lacks clarity on the resource type. It does not differentiate from sibling list tools like hotmart_modules_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'Requires module_id from hotmart_modules_list first.' This gives clear sequencing guidance, though it does not specify when not to use the tool 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 Modules. Lists module containers only. To get pages inside a module, use hotmart_module_pages_list with the module_id.
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | Members area subdomain (the slug from `hotmart.com/club/<slug>` URL) | |
| is_extra | No | Filtrar módulos extras | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States it lists module containers only, which is clear for a read operation, but doesn't explicitly declare read-only behavior or other traits like rate limits or side effects.
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 wasted words, directly states purpose and direction to sibling tool. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It adequately covers the purpose, scope, and usage for a simple listing 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 coverage is 100%, so baseline 3. Description does not add meaning beyond the already descriptive parameter descriptions in the schema, such as 'Filtrar módulos extras' for is_extra.
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 'Get Modules' and specifies 'Lists module containers only', distinguishing it from sibling tool hotmart_module_pages_list which gets pages inside a module.
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 to hotmart_module_pages_list for pages inside a module, providing clear alternative usage. No exclusions or when-not guidance, but sufficient for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate Negotiation.
| Name | Required | Description | Default |
|---|---|---|---|
| subscription_id | Yes | ID da assinatura | |
| recurrences | Yes | Números das recorrências em atraso (1 a 5 valores). Pass a JSON array of integers, e.g. `[12345, 67890]`. | |
| payment_type | Yes | Payment type para a negociação. Allowed values: 'BOLETO', 'PIX' | |
| discount | No | discount. **Fraction between 0 and 1** (NOT percent). Ex: `0.25` = 25% off. Pass `0.10` for 10%, NOT `10`. | |
| document | No | Subscriber's CPF or CNPJ (required when payment_method is BILLET) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, and the description discloses no behavioral traits (e.g., whether it creates a record, requires authentication, or is destructive). The description is too brief to communicate any side effects or prerequisites.
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 short (2 words), but this is under-specification rather than effective conciseness. It fails to provide necessary context, wasting the opportunity to convey purpose and usage.
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 5-parameter (3 required) input and existence of an output schema, the description is insufficient. It does not explain the tool's core function (generating a negotiation) or how it relates to subscription management. The high schema and output schema richness do not compensate for the vague description.
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 detailed parameter descriptions (e.g., discount specifies fraction between 0 and 1). The tool description adds no extra value beyond the schema, earning the baseline score of 3.
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 'Generate Negotiation' is a tautology of the tool name. It does not specify the type of negotiation (e.g., for overdue subscriptions) or what the tool actually produces (e.g., a negotiation link or agreement). It lacks specific verb+resource clarity beyond the name itself.
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 alternatives. Sibling tools include hotmart_subscription_cancel, hotmart_subscription_reactivate, and many negotiation-related apps, but the description provides no differentiation or context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview de proposta de negociação antes de gerar.
Mostra os parâmetros e dispara o hotmart_negotiation_generate se
confirmado. Use pra 'simular negociação pro assinante X', 'preview
parcelamento'. NÃO gera por padrão — só prévia visual.
| Name | Required | Description | Default |
|---|---|---|---|
| subscription_id | Yes | ID/code da assinatura inadimplente. | |
| payment_type | No | BILLET | PIX | CREDIT_CARD. **Note: API uses English 'BILLET' (NOT 'BOLETO')**. | BILLET |
| recurrences | No | Número de parcelas (1 = à vista). | |
| discount | No | Desconto como **fração 0-1** (ex: 0.25 = 25% off). NOT percent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it shows parameters and triggers generate if confirmed, and explicitly says it does not generate by default. With no annotations, it partially compensates but does not disclose what happens after confirmation or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the core purpose. It efficiently conveys the tool's primary function and relationship to generate, with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description covers the tool's function and usage context well. It could be improved by hinting at what the preview outputs (e.g., calculated values) but is sufficient 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?
Input schema has 100% coverage with parameter descriptions. The description does not add new meaning beyond schema; it only reinforces the preview purpose. 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 it is a 'Preview de proposta de negociação' before generating, and identifies the specific resource (negotiation proposal). It distinguishes itself from the sibling tool hotmart_negotiation_generate by noting it triggers generate only upon confirmation.
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 explicit usage contexts like 'simular negociação pro assinante X' and 'preview parcelamento', and clarifies it does not generate by default. However, it does not mention when not to use it or provide alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Catálogo de produtos — visão geral com formato/status/preço/info.
Cards de metrics + PieChart status + DataTable. Use pra 'lista de produtos', 'catálogo', 'meus produtos ativos'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the visual elements (cards, piechart, datatable) but fails to disclose key behavioral traits like whether the tool is read-only, its authorization requirements, or any rate limits. As a catalog tool, it is likely read-only, but this is not stated.
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 very concise, with a clear front-loaded title ('Catálogo de produtos — visão geral...') followed by bullet-point-like details. Every sentence adds useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no input parameters and no output schema, the description provides sufficient context: purpose, visual elements, and usage phrases. It does not mention whether it's read-only or if there are any default filters, but for a simple catalog overview, it's mostly 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 no parameters, so the description does not need to explain parameter meaning. However, it adds value by describing the output format (metrics cards, piechart, datatable), which compensates for the absence of output schema. Baseline for 0 parameters is 4, and the description meets that.
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's a product catalog overview with format/status/price/info and includes visual elements like cards, piechart, and datatable. It also provides usage phrases ('lista de produtos', 'catálogo'). However, it does not explicitly differentiate from sibling tools like hotmart_products_list, which might be a similar list view.
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 usage phrases ('Use pra 'lista de produtos', 'catálogo', 'meus produtos ativos''), implying when it should be used. However, it offers no guidance on when not to use it or alternatives among the many sibling tools, such as hotmart_sales_dashboard_app for sales data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Product Offers. Example: hotmart_product_offers_list(product_id=12345, max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| offer_key | No | Offer key | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks details on behavioral traits such as pagination behavior, rate limiting, or idempotence. The example call hints at pagination via 'max_results' but does not explain it.
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 very short (two sentences) and efficient. However, it could be better structured with a more explanatory sentence about what the tool returns.
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 having an output schema, the description does not mention return values or pagination details. With 5 parameters and a pagination token, the description leaves significant gaps in understanding the tool's full behavior.
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?
Input schema has 100% coverage with descriptions for all parameters. The description adds an example usage (product_id, max_results) which aids clarity but does not provide additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'Product Offers', and the tool name reinforces this. It is distinct from sibling tool names like hotmart_products_list or hotmart_sales_history_list, avoiding ambiguity.
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?
Only an example call is provided with no guidance on when to use this tool versus alternatives like hotmart_products_list or hotmart_sales_history_list. No explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Product Plans. Example: hotmart_product_plans_list(product_id=12345, max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| id_ | No | ID do plano | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 such as read-only nature, pagination behavior, or rate limits. The description is insufficient to compensate for missing 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?
The description is extremely concise with one sentence and an example. No unnecessary words, and the example provides quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no annotations, the description is incomplete. It does not explain pagination, filtering by plan ID, or the custom select feature. The presence of an output schema does not compensate for missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the schema already documents parameters. The description adds minimal value by showing an example with product_id and max_results, but other parameters (page_token, id_, select) are not addressed.
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 'Get Product Plans' with an example, providing a clear verb and resource. However, it does not differentiate from siblings like hotmart_product_offers_list, which could also deal with product-related 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 is given on when to use this tool versus alternatives. The description lacks when-to-use, when-not-to-use, or mentions of related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Products. Example: hotmart_products_list(max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| id_ | No | Product ID | |
| status | No | Status do produto. | |
| format_ | No | Formato do produto. | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose behavioral traits such as pagination behavior, filtering logic, or side effects. The example only shows one parameter but no return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the purpose. It is efficient, though it sacrifices completeness for brevity.
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 having an output schema, the description is too sparse for a tool with 6 optional parameters. Lacks explanation of pagination, filtering, and common use cases, making it 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 has 100% coverage, so baseline is 3. The description adds minimal value beyond the schema with an example, but does not explain parameter semantics further.
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 'List Products' with a verb and resource. It is unambiguous but does not explicitly differentiate from sibling list tools like hotmart_coupons_list or hotmart_sales_history_list. The example usage adds clarity.
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 alternatives. The description lacks context for typical use cases, prerequisites, or scenarios where it is applicable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales Refund. Example: hotmart_sale_refund(transaction_code='ABC123XY').
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_code | Yes | Transaction code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not mention side effects (e.g., does it reverse a transaction permanently?), permission requirements, rate limits, or success/failure behavior. The agent is left uninformed about the tool's impact.
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: one sentence and one example. It is front-loaded with the purpose and includes a practical example, with no unnecessary 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's simplicity (one required parameter, output schema present), the description provides minimal but sufficient information to understand the basic operation. However, it lacks behavioral context that would help an agent handle errors or side effects, making it adequate but not comprehensive.
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 schema provides 100% coverage for the single parameter, but the description adds an example showing the exact format (transaction_code='ABC123XY'), which is more concrete than the schema's description. This helps the agent understand the expected input pattern.
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 'Sales Refund' and provides an example call, making the purpose clear. However, it does not explicitly differentiate from sibling tools like hotmart_sales_summary_list, leaving room for confusion if multiple tools could be applied.
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 is given on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or when to avoid using it. The description lacks any decision support for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Breakdown de vendas — top produtos + top compradores.
BarChart de produtos por receita + DataTable de compradores únicos. Use pra 'quais produtos vendem mais', 'top compradores', 'analise de quem está comprando'.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date. Unix timestamp in milliseconds. | |
| end_date | No | End date. Unix timestamp in milliseconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes the output (bar chart, data table) but omits details like read-only nature, authentication requirements, or data freshness, which are important for a tool with no annotation support.
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: three short sentences that capture purpose, output format, and use cases without redundancy. 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?
Given the simplicity (two optional params, no output schema, no annotations), the description adequately covers purpose, output, and usage. A minor gap is the lack of explanation about date range behavior when both params are null, but overall it 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 coverage is 100% with clear parameter descriptions (Unix timestamps). The tool description adds no extra parameter information 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?
Description explicitly states the tool provides a breakdown of top products and top buyers, and lists specific use cases like 'quais produtos vendem mais' and 'top compradores', clearly distinguishing it from sibling tools such as generic sales lists or dashboards.
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 concrete usage scenarios ('quais produtos vendem mais', etc.) that guide when to use it, but does not explicitly mention when not to use it or compare to alternatives, which is acceptable given the clear purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales Commissions. Example: hotmart_sales_commissions_list(max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| start_date | No | Start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | End date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| transaction | No | Transaction code | |
| commission_as | No | Authenticated user's commission role. Allowed values: 'PRODUCER', 'COPRODUCER', 'AFFILIATE' | |
| transaction_status | No | Transaction status. | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and no description of behavioral traits such as read-only, destructive actions, rate limits, or data scope. The description is silent on these.
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?
Extremely short but under-informative. The example sentence is minimal and doesn't convey essential 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?
With 9 parameters, no output schema details, and no behavioral transparency, the description is severely incomplete, leaving the agent without sufficient context to use 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 description doesn't need to add parameter details. However, it adds no value beyond what's in the schema, meeting 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?
Description merely states 'Sales Commissions' which is vague and does not specify the action (list, get?) or distinguish from siblings. The example shows a call but lacks a clear verb.
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 vs siblings. There are many list tools on the server, but no differentiation provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Painel visual de vendas Hotmart no período.
Cards de métricas (receita total, ticket médio, qtd) + LineChart vendas/dia + PieChart por payment_type + DataTable. Use quando o usuário pedir 'dashboard de vendas', 'painel de vendas', 'visão geral das vendas do mês'.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date. Unix timestamp in milliseconds. | |
| end_date | No | End date. Unix timestamp in milliseconds. | |
| product_id | No | Optional product_id filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes the output components but does not state whether the operation is read-only, if authentication is required, or what happens when no parameters are given (default period). The lack of any mutating or destructive hint leaves ambiguity.
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: first introduces the dashboard, second lists components, third gives usage triggers. It is front-loaded and every sentence contributes essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the many sibling dashboard tools, the description adequately explains the visual output (cards, charts, table). It does not detail default behavior for date range or pagination, but the schema covers parameters. No output schema exists, but the description compensates by listing output elements.
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 clear descriptions for each parameter (start_date, end_date, product_id). The tool description adds no additional meaning beyond what the schema already provides. Baseline of 3 applies since description does not compensate beyond 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 specifies the tool shows a visual sales dashboard with metric cards (revenue, average ticket, quantity), line chart, pie chart, and data table. It identifies the resource ('vendas' - sales) and the verb is implied (dashboard/display). This distinguishes it from sibling dashboards like commissions or 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 lists user phrases that trigger this tool ('dashboard de vendas', 'painel de vendas', 'visão geral das vendas do mês'). This provides clear context for when to use. However, it does not mention when not to use or suggest alternative tools for more detailed breakdowns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales History. Example: hotmart_sales_history_list(max_results=10). Don't use this for aggregated metrics — use hotmart_sales_summary_list for totals/counts.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| start_date | No | Start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | End date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| sales_source | No | Sale source | |
| transaction | No | Transaction code | |
| select | No | Custom field selection in response | |
| buyer_name | No | Buyer name | |
| buyer_email | No | Buyer email | |
| offer_code | No | Offer code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| commission_as | No | Authenticated user's commission role. Allowed values: 'PRODUCER', 'COPRODUCER', 'AFFILIATE' | |
| transaction_status | No | Transaction status. | |
| payment_type | No | Payment type. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. However, it only says 'Sales History' and gives an example, omitting details like pagination behavior, authentication requirements, rate limits, or the nature of the response. This is insufficient for a tool with 14 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?
The description is extremely concise with only two sentences and an example. Every part serves a purpose: stating what it does, giving a usage example, and providing an exclusion. 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?
Despite having an output schema (not shown) and full parameter documentation in the schema, the description lacks essential contextual information such as how pagination works with page_token, the format of dates (though partially in param description), or what the response contains. For a complex tool with 14 parameters, more context is needed beyond the schema.
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%, meaning all parameters have descriptions in the schema. The tool description does not add significant meaning beyond the schema; it only provides a usage example. Baseline 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 clearly states 'Sales History' and provides an example of usage. It distinguishes itself from the sibling tool `hotmart_sales_summary_list` by specifying when not to use it (for aggregated metrics), making the purpose very clear.
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 advises against using this tool for aggregated metrics and directs the user to `hotmart_sales_summary_list` instead, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales Participants. Example: hotmart_sales_participants_list(transaction_status='APPROVED').
| Name | Required | Description | Default |
|---|---|---|---|
| transaction | No | Transaction code | |
| transaction_status | No | Transaction status. | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| start_date | No | Start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | End date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| buyer_email | No | Buyer email | |
| sales_source | No | Sale source | |
| buyer_name | No | Buyer name | |
| affiliate_name | No | Nome do afiliado | |
| commission_as | No | Authenticated user's commission role. Allowed values: 'PRODUCER', 'COPRODUCER', 'AFFILIATE' | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 not disclose pagination, rate limits, read-only behavior, or any side effects. The example only shows a parameter call.
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 very short (one sentence plus example), which is concise but under-specified. It could benefit from a bit more detail without being verbose.
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 high schema coverage and an output schema, the description is too vague. For 13 parameters, more context on what 'Sales Participants' entails and how results are structured is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds an example usage which provides a common pattern, but adds no additional semantic meaning beyond 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 states it lists sales participants, but it is too brief and does not differentiate from sibling tools like hotmart_sales_history_list or hotmart_sales_summary_list. The example shows a parameter but lacks specificity.
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 alternatives. The example is a usage pattern but does not provide context on selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales Price Details. Example: hotmart_sales_price_details_list(transaction_status='APPROVED').
| Name | Required | Description | Default |
|---|---|---|---|
| transaction | No | Transaction code | |
| transaction_status | No | Transaction status. | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| start_date | No | Start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | End date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| payment_type | No | Payment type. | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose behavioral traits such as read-only nature, pagination, or rate limits. The example only shows a single use case.
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 very short (one line plus an example), which is concise but lacks detail. It could be expanded without being verbose.
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 9 parameters and a likely complex output (though output schema exists), the description provides minimal context. It does not explain pagination, return values, or typical use cases.
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 clear descriptions for each parameter (e.g., start_date explains Unix timestamp in milliseconds). The description adds no extra meaning, but the schema itself is adequate.
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 'Sales Price Details' is vague and does not specify the action (list, get, etc.) or distinguish from sibling tools like commissions or breakdown. The example adds context but not clarity.
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 vs. other sales-related tools. The example implies filtering by transaction_status but does not explain when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales Summary. Example: hotmart_sales_summary_list(transaction_status='APPROVED'). Don't use this for per-transaction details — use hotmart_sales_history_list for the raw list.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction | No | Transaction code | |
| transaction_status | No | Transaction status. | |
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| start_date | No | Start date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date | No | End date. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| sales_source | No | Sale source | |
| affiliate_name | No | Nome do afiliado | |
| payment_type | No | Payment type. | |
| offer_code | No | Offer code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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. However, it only gives a bare example and does not explain whether the function is read-only, what aggregation occurs, or what the output structure looks like. For a tool named 'summary', the lack of detail about grouping or calculation 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 two sentences with an inline example, no redundant information, and front-loaded with the key purpose. Every word 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?
Given 12 parameters, an output schema exists but is not described, and no annotations, the description is far too minimal. It omits what a 'sales summary' entails (e.g., grouped totals, time periods), the meaning of the output, or how to use parameters like 'select'. The tool's complexity demands more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds an example usage but no additional parameter semantics beyond what the schema already provides. The schema descriptions are adequate but not enriched by the tool description.
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 'Sales Summary' and provides an example with 'transaction_status='APPROVED'', which clearly indicates it returns aggregated sales data. It also explicitly distinguishes from 'hotmart_sales_history_list' for per-transaction details, so the purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Don't use this for per-transaction details — use `hotmart_sales_history_list` for the raw list.' This provides clear when-to-use and when-not-to guidance, including naming the alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Student Progress. Example: hotmart_student_progress_get(user_id='…').
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | ID do aluno | |
| subdomain | Yes | Members area subdomain (the slug from `hotmart.com/club/<slug>` URL) | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are missing, so the description must carry the full burden. It only states the basic function without disclosing side effects, authentication needs, or output structure (though an output schema exists but is not referenced).
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 very short and front-loaded with the most critical info (action and example). It earns its place but could benefit from a bit more detail without becoming verbose.
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 having an output schema and well-defined parameters, the description is too minimal. It does not explain what 'progress' entails, how the response is structured, or any limitations. For a tool with many siblings, this is insufficient.
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 adds minimal value beyond the schema, only providing an example call that illustrates the 'user_id' parameter. No additional semantic context is given.
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 Student Progress' with an example call, indicating the action and resource. However, it does not differentiate from sibling tools like hotmart_students_list or hotmart_students_overview_app, which limits clarity in a crowded context.
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 is provided on when to use this tool versus alternatives, such as other student-related tools. The description lacks context about prerequisites or intended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Students.
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | Members area subdomain (the slug from `hotmart.com/club/<slug>` URL) | |
| No | Email do aluno | ||
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It reveals nothing about what the tool returns, filtering capabilities, pagination, required permissions, or side effects. This is insufficient for a data retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is too terse to be useful. Conciseness should not come at the expense of clarity; it lacks essential context and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description still fails to explain the tool's scope (e.g., list of all students vs. filtered, paginated). Compared to many sibling tools, it omits critical details for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage), so the description does not need to add much. However, it adds no additional meaning beyond what the schema already provides, which is merely adequate.
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 'Get Students' is extremely vague. It does not specify what 'students' refers to (e.g., course students, members) and fails to differentiate from sibling tools like hotmart_students_overview_app or hotmart_student_progress_get.
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 is provided on when to use this tool versus alternatives. With many sibling tools focusing on students and subscriptions, the lack of contextual advice makes it hard for an agent to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Visão geral dos alunos na área de membros — counts + progresso.
Cards (total, ativos, bloqueados) + PieChart engajamento + DataTable ranking. Use pra 'lista de alunos', 'progresso médio', 'quantos alunos completaram'.
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | Members area subdomain (slug de `hotmart.com/club/<slug>`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits like permissions, rate limits, or side effects. It describes the output but lacks detail on data freshness or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficiently conveys the tool's purpose and output components. It uses a bullet-like structure but could be slightly more organized.
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 single well-described parameter and no output schema, the description adequately covers what the tool does and provides usage examples. It meets the needs for a dashboard overview 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?
The input schema has 100% coverage with a well-described parameter (subdomain). The description does not add any additional semantic information beyond what the schema already provides, so baseline score applies.
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 provides an overview of students with counts and progress, listing specific visual components (cards, pie chart, data table). This distinguishes it from sibling tools like hotmart_students_list and hotmart_student_progress_get.
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 concrete use cases ('lista de alunos', 'progresso médio', 'quantos alunos completaram') which guide when to use the tool, though it does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Visão 360 de um assinante — perfil + histórico de compras.
Cards de LTV/qty/ticket + DataTable com purchases. Use pra 'ver dados do assinante X', 'histórico completo do código Y'.
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | Subscriber code (Hotmart alphanumeric, ex: 'VRWIQQRG'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states the tool shows a 360 view but does not disclose any behavioral traits such as data freshness, required permissions, or side effects. For a read-only data display, this is insufficient.
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 very concise, consisting of two sentences that front-load the purpose and provide usage examples. Every word contributes 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?
Given the tool's simplicity (one parameter, no output schema), the description is mostly complete. It explains the purpose and gives example use cases. However, it could be more explicit about the exact fields returned (like LTV, qty, ticket) since they are mentioned in the UI context but not as structured output.
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 for the single parameter subscriber_code, which is well-defined. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.
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 it provides a '360 view of a subscriber' with profile and purchase history, and lists specific UI elements like LTV/qty/ticket cards and a DataTable. This distinguishes it from siblings like hotmart_subscriber_purchases_list which only lists purchases.
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 example phrases like 'view data of subscriber X' and 'complete history of code Y', giving clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscriber Purchases. Example: hotmart_subscriber_purchases_list(subscriber_code='ABC123XY').
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Behavioral traits are completely absent. The description does not disclose if the tool is read-only, requires specific authentication, has rate limits, or returns a subset of transactions. With no annotations, the description should carry this burden but fails entirely.
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 very short (two sentences), but one sentence is just an example. It is not structurally informative; it lacks headings or readability aids. It could be more concise while including more substance.
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 the presence of an output schema, the description fails to provide contextual completeness. It does not explain what constitutes a purchase, the scope of data returned, or any error conditions. A simple tool with one parameter still benefits from minimal guidance on invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full parameter description (format examples, constraints). The description adds only an example call, which provides no new semantic meaning beyond the schema. With 100% coverage, 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 states 'Subscriber Purchases' which conveys the general purpose of listing purchases for a subscriber, but it lacks specificity to distinguish it from sibling tools like hotmart_subscription_transactions_list or hotmart_sales_history_list, which might also involve purchases. The example provides a usage pattern but no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives, nor does it mention any prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel Subscription. Example: hotmart_subscription_cancel(subscriber_code='ABC123XY'). Use this for ONE subscriber_code. For 2+ subscriptions, use hotmart_batch_subscriptions_cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| send_mail | No | Enviar e-mail de notificação ao assinante |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose behavioral traits such as side effects (e.g., immediate cancellation, refund impact, reversibility) or permission requirements. It only repeats parameter format from 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 highly concise: two sentences front-loading the purpose, example, and usage guidance. Every sentence earns its place with no unnecessary 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% schema coverage, the description covers basic usage but lacks details on cancellation consequences, default behavior of send_mail, and required permissions. It is adequate but incomplete for a mutation 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%, baseline is 3. The description does not add meaning beyond the schema; it only provides an example that reiterates the schema's format. No additional parameter 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 explicitly states 'Cancel Subscription' and provides a clear example. It distinguishes this tool from its sibling by noting it is for a single subscriber_code, while batch cancel is for multiple.
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 clearly states when to use this tool: for one subscriber_code. It explicitly directs users to an alternative sibling tool (hotmart_batch_subscriptions_cancel) for multiple subscriptions, providing unambiguous usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change Due Day. Example: hotmart_subscription_due_day_update(subscriber_code='ABC123XY').
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| due_day | Yes | Novo dia de vencimento (1-31) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden. It only says 'Change Due Day' without disclosing side effects, authorization needs, or constraints beyond the schema. The example is incomplete (omits due_day), which may confuse.
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?
Description is concise with one functional sentence and an example. However, the example is partially incorrect (missing due_day), reducing clarity. Still, it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple action and two parameters, the description is minimally adequate. But the lack of usage context and an incomplete example prevent it from being fully helpful. Output schema exists but is not leveraged.
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 minimal value with an example, but the example is incomplete. It does not clarify parameter semantics beyond what the schema already 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?
Description explicitly states 'Change Due Day', which is a specific action on a subscription resource. Sibling tools cover different operations (cancel, reactivate, list), so this tool is clearly distinguished.
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 alternatives, no prerequisites or exclusions. A simple two-word description provides no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reactivate Subscription. Example: hotmart_subscription_reactivate(subscriber_code='ABC123XY'). Use this for ONE subscriber_code. For 2+, use hotmart_batch_subscriptions_reactivate.
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_code | Yes | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| charge | No | Cobrar imediatamente |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It does not disclose side effects, permissions, or what the charge parameter does (Portuguese only). Only the basic action is stated.
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?
Extremely concise: two sentences and an example. No wasted words; all sentences are essential.
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?
Output schema exists, so return values don't need explanation. However, for a mutation tool with no annotations, more behavioral context (e.g., what charge=true does) would improve completeness. The current description is functional but minimal.
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%, baseline is 3. Description does not add meaning beyond schema; the charge parameter's effect is not explained in English, and no additional context for subscriber_code is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Reactivate Subscription) and resource, with an example and explicit differentiation from the batch sibling tool. The verb and resource are specific and distinct.
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 states to use for one subscriber_code and directs to hotmart_batch_subscriptions_reactivate for multiple, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Painel de saúde das assinaturas — counts por status + lista.
Grid com cards (ativos, atrasados, cancelados) + PieChart breakdown
DataTable. Use pra 'saúde das assinaturas', 'visão geral das assinaturas', 'quantos assinantes ativos'.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | No | Optional product_id filter. |
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 describes the output (cards, pie chart, data table) but does not explicitly state that the tool is read-only or disclose other behavioral traits like authentication or rate limits. The visual description helps but lacks 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?
The description is concise and front-loads the purpose. It uses efficient language and includes practical usage examples. However, it could be slightly more structured (e.g., separating output description from usage hints).
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 dashboard tool with one optional parameter and no output schema, the description provides a clear picture of the output (cards, pie chart, data table) and the kind of queries it addresses. It is complete enough for the tool's complexity.
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 schema coverage is 100% with a clear description for product_id. The tool description does not add new parameter information beyond the schema, but it implies that the output can be filtered by product. A score of 3 is appropriate as the schema already handles parameter semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: providing a health panel for subscriptions with counts by status (active, overdue, canceled) and visual elements like cards, a pie chart, and a data table. It distinguishes itself from siblings like hotmart_subscriptions_list or hotmart_subscriptions_summary_list by focusing on the overview/health aspect.
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 suggests when to use the tool: for phrases like 'saúde das assinaturas', 'visão geral das assinaturas', and 'quantos assinantes ativos'. This provides clear context, though it does not explicitly exclude alternatives or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Subscriptions. Example: hotmart_subscriptions_list(max_results=10). Don't use this for payment events — use hotmart_subscription_transactions_list for charges/refunds per subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| plan | No | Nomes dos planos. Pass a JSON array of strings, e.g. `['ABC123XY', 'DEF456ZW']`. | |
| plan_id | No | ID do plano | |
| accession_date | No | Subscription start date (lower bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_accession_date | No | Subscription start date (upper bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| status | No | Subscription status. | |
| subscriber_code | No | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| subscriber_email | No | Email do assinante | |
| transaction | No | Transaction code | |
| trial | No | Filtrar por trial | |
| cancelation_date | No | Data de cancelamento inicial. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_cancelation_date | No | Data de cancelamento final. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| date_next_charge | No | Data da próxima cobrança inicial. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_date_next_charge | No | Data da próxima cobrança final. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden for behavioral disclosure. It only says 'Get Subscriptions' with an example, but does not disclose authentication needs, rate limits, pagination behavior, or any side effects. For a listing tool with no annotations, this is insufficient 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?
The description is very concise at two sentences. The first sentence is minimal but the second effectively differentiates from a sibling. While efficient, it could be restructured to front-load more useful context for the agent. Still, no unnecessary 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's complexity (17 parameters, no required fields, output schema present), the description is too brief. It lacks guidance on typical use cases, filtering strategies, or how pagination works. The parameter descriptions in the schema are detailed, but the tool description itself does not synthesize this into actionable context for the 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?
Schema description coverage is 100%, so the schema already documents all 17 parameters. The description adds a usage example with 'max_results=10', but does not provide additional semantic context beyond what the schema offers. Baseline is 3 due to high coverage, and the description adds minimal extra value.
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 Subscriptions' and provides a usage example. It explicitly distinguishes from the sibling tool 'hotmart_subscription_transactions_list' by stating not to use it for payment events, ensuring the agent selects the correct 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?
The description gives explicit guidance on when not to use the tool ('Don't use this for payment events') and names the alternative ('use hotmart_subscription_transactions_list'). However, it does not elaborate on broader usage context or when to choose this tool over other subscription-related siblings like cancel or reactivate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscription Summary. Example: hotmart_subscriptions_summary_list(max_results=10).
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| subscriber_code | No | Subscriber code | |
| accession_date | No | Subscription start date (lower bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_accession_date | No | Subscription start date (upper bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| date_next_charge | No | Data da próxima cobrança. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as read-only, pagination, or error handling. It only gives an example call, failing to inform about side effects or performance implications.
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 brief but under-specified. It lacks structure and fails to convey essential information, sacrificing completeness for brevity.
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 8 parameters and output schema, the description is insufficient. It does not explain the summary content, pagination with page_token, or return format, leaving significant 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?
Input schema parameters are well-documented with 100% coverage, so the description adds minimal value beyond the example. The example shows usage for max_results but does not enhance understanding of other parameters.
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 'Subscription Summary' is vague and does not clearly state what the tool does. It does not differentiate from sibling tools like hotmart_subscriptions_list, leaving confusion about its specific purpose.
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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscription Transactions. Example: hotmart_subscription_transactions_list(max_results=10). Don't use this for the subscription list itself — use hotmart_subscriptions_list.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max results per page | |
| page_token | No | Pagination token for the next page | |
| product_id | No | Product ID | |
| transaction | No | Transaction code | |
| subscriber_name | No | Nome do assinante | |
| subscriber_email | No | Email do assinante | |
| billing_type | No | Tipo de cobrança. Allowed values: 'SUBSCRIPTION', 'SMART_INSTALLMENT', 'SMART_RECOVERY' | |
| subscription_status | No | Subscription status. | |
| recurrency_status | No | Status da recorrência. | |
| purchase_status | No | Status da compra | |
| transaction_date | No | Data da transação inicial. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| end_transaction_date | No | Data da transação final. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`. | |
| offer_code | No | Offer code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| purchase_payment_type | No | Payment type da compra. | |
| subscriber_code | No | Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int) | |
| select | No | Custom field selection in response |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden of behavioral disclosure. However, it only repeats the tool's purpose and gives an example, without mentioning idempotency, rate limits, pagination behavior, or side effects. The description adds minimal behavioral context beyond the obvious.
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 that cover purpose, example, and a sibling distinction. Every sentence is necessary and no word 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?
The tool is complex with 16 parameters, but the description is minimal. With an output schema present (as indicated), the description does not need to detail return values. However, it lacks context on pagination, filtering, and typical use cases beyond the example. Adequate but could be more 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 descriptions for all 16 parameters, including detailed notes (e.g., transaction_date explains the milliseconds format). The tool description only shows an example using max_results, but does not add new meaning beyond what the schema already provides. The baseline is 3 given the high schema coverage.
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 'Subscription Transactions' and gives an example usage. It also distinguishes from the sibling tool hotmart_subscriptions_list by explicitly saying not to use this for the subscription list itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use the tool ('Don't use this for the subscription list itself') and directs to the correct sibling tool (hotmart_subscriptions_list). This is a clear alternative and context for use.
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.4.1hotmart_students_overview_app1 field changedInput schema / properties / subdomain / descriptionPrevious value: -"Members area subdomain (the slug from `hotmart.com/club/<slug>`)."New value: +"Members area subdomain (slug de `hotmart.com/club/<slug>`)."v0.3.3hotmart_batch_subscriptions_cancelhotmart_batch_subscriptions_reactivatehotmart_churn_analyzer_apphotmart_commissions_dashboard_apphotmart_coupon_createhotmart_coupon_deletehotmart_coupon_manager_apphotmart_coupons_listhotmart_event_dashboard_apphotmart_event_info_gethotmart_event_participants_listhotmart_module_analytics_apphotmart_module_pages_listhotmart_modules_listhotmart_negotiation_generatehotmart_negotiation_preview_apphotmart_product_catalog_apphotmart_product_offers_listhotmart_product_plans_listhotmart_products_listhotmart_sale_refundhotmart_sales_breakdown_apphotmart_sales_commissions_listhotmart_sales_dashboard_apphotmart_sales_history_listhotmart_sales_participants_listhotmart_sales_price_details_listhotmart_sales_summary_listhotmart_student_progress_gethotmart_students_listhotmart_students_overview_apphotmart_subscriber_360_apphotmart_subscriber_purchases_listhotmart_subscription_cancelhotmart_subscription_due_day_updatehotmart_subscription_reactivatehotmart_subscription_transactions_listhotmart_subscriptions_health_apphotmart_subscriptions_listhotmart_subscriptions_summary_listv0.2.1batch_cancel_subscriptionsbatch_reactivate_subscriptionscancel_subscriptionchange_subscription_due_daycreate_coupondelete_coupongenerate_negotiationget_couponsget_event_infoget_event_participantsget_module_pagesget_modulesget_product_offersget_product_plansget_sales_commissionsget_sales_historyget_sales_participantsget_sales_price_detailsget_sales_summaryget_student_progressget_studentsget_subscriber_purchasesget_subscription_transactionsget_subscriptionsget_subscriptions_summarylist_productsreactivate_subscriptionrefund_salev0.1.0batch_cancel_subscriptionsbatch_reactivate_subscriptionscancel_subscriptionchange_subscription_due_daycreate_coupondelete_coupongenerate_negotiationget_couponsget_event_infoget_event_participantsget_module_pagesget_modulesget_product_offersget_product_plansget_sales_commissionsget_sales_historyget_sales_participantsget_sales_price_detailsget_sales_summaryget_student_progressget_studentsget_subscriber_purchasesget_subscription_transactionsget_subscriptionsget_subscriptions_summarylist_productsreactivate_subscriptionrefund_saleScored across 40 tools
Most tools target distinct resources and actions, and descriptions explicitly disambiguate similar ones (e.g., sales_history_list vs sales_summary_list, subscription_cancel vs batch_subscriptions_cancel). The main overlap risk is among the many `_app` dashboard tools, but each has a clear analytical scope.
Naming generally follows `hotmart_<resource>_<action>` (e.g., hotmart_coupon_create, hotmart_subscription_cancel) and is quite consistent. Minor deviations include `hotmart_event_info_get` (get at end), batch variants like `hotmart_batch_subscriptions_cancel`, and many `_app` suffixes for dashboard tools, which feel like a separate convention.
At 40 tools, this is far beyond the 3–15 typical well-scoped range and above the 25+ threshold. Many overlapping app dashboards, listing variants, and batch/single pairs inflate the count beyond what seems necessary for the core Hotmart domain.
The surface covers a wide range: products, offers, subscriptions, sales, students, coupons, and events. However, there are notable gaps like no product create/update/delete, no page management, and no individual sale fetch/update, leaving some workflows incomplete.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
Insights for your iFood store right in your AI assistant's chat. Generate charts of sales and payout
Manage your Savanto store from your AI: catalog, content, prompts, and analytics, by chat.
