Guia da Maquininha

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

No annotations are provided, so the description carries the full behavioral burden. It implies a pure computation but never states that it is side-effect free, requires no auth, or how the result should be interpreted; the only added behavior is the word 'monthly'.

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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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 no output schema and no annotations, the description should say what is returned (a number, a currency-formatted value, a breakdown?) and whether anticipation changes the shape of the result. It covers inputs adequately but leaves the return contract unaddressed.

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 each of the three parameters documented (including tier and brand vocabularies and the anticipation flag's meaning). The description adds no syntax or semantic detail beyond the schema, so the baseline 3 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?

States a specific verb (Calculate) and resource (monthly cost) plus the three inputs that scope it, so an agent can tell it apart from compare_brands/get_brands/get_tiers. It is clear, though it never explicitly contrasts itself with those siblings.

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

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

There is no when-to-use guidance, no statement of when to prefer compare_brands or get_tiers first, and no prerequisites (e.g., needing valid brand/tier keys from the sibling lookup tools). Usage is only implied by the parameter names.

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

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

With no annotations, the description carries the full burden, and it does disclose the return concept (a ranking by cost). However, it does not state sort direction, whether the ranking is ascending/descending, tie behavior, or how the antecipation option affects ordering. Read-only nature is strongly implied by 'compare' and 'return' but never 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?

One sentence, front-loaded with the action and resource, then scope and output. Nothing redundant or padded.

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 two-parameter read tool with no output schema, the description states the scope and the shape of the result (ranking by cost), which is enough to call it correctly. It could still say whether the ranking includes anticipation fees by default, which is the one open question.

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 both parameters (tier with its enum values, antecipation with its default) are already fully documented in the schema. The description adds no extra semantics such as how antecipation changes the comparison, so the 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 gives a specific verb (compare), a resource (all brands), a scope (a specific tier), and even the output dimension (ranking by cost). This clearly separates it from get_brands (list raw brands) and calculate_cost (single cost), though it never names those siblings explicitly.

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

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

Usage is implied — use this when you want a cost ranking across brands within one tier — but there is no explicit when-to-use statement, no exclusion conditions, and no mention of calculate_cost or get_brands as alternatives. An agent must infer the choice from the verb alone.

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

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

No annotations are provided, so the description carries the burden. It discloses the returned content (brands with debit/credit MDR rates), which is useful, but says nothing about ordering, pagination, or data freshness. For a zero-parameter read-only listing the required burden is low, so this is adequate but thin.

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?

A single front-loaded sentence with no filler; the resource and its returned fields are stated immediately.

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 no output schema, the description compensates by naming the fields returned (MDR rates for debit and credit). For a no-param, no-annotation listing tool this is nearly complete, though it omits ordering/currency 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 tool takes zero parameters, so there are no parameter semantics to document and the baseline is 4. The description correctly implies no inputs by describing an unfiltered list of all brands.

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 specific verb (List) and resource (card machine brands), plus the returned attributes (MDR rates for debit and credit). An agent can distinguish it from calculate_cost, compare_brands, and get_tiers by the fact it enumerates brands rather than computing or comparing. It stops short of naming a sibling to differentiate against.

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 when-to-use or when-not-to-use guidance, but the listing nature implies it is the discovery step before compare_brands or calculate_cost. The context is inferable, not stated.

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

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

With no annotations, the description carries the full behavioral burden, but for a zero-parameter lookup the surface is small. It usefully discloses the payload shape (ticket average and monthly volume accompany each tier), which partially compensates for the absent output schema, yet it says nothing about auth needs, caching, or whether values are static or computed.

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?

A single front-loaded sentence with no filler; the resource comes first and the returned fields follow as a compact parenthetical. Nothing could be removed without losing information.

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

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

For a simple zero-arg retrieval tool with no output schema, the description supplies the essential missing piece: what each returned tier includes. The remaining gap is context on the domain (business/pricing tiers) and any relationship to calculate_cost, which would help an agent chain calls.

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

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

The tool takes zero parameters, so per the baseline there is no parameter semantics to document. The description correctly avoids inventing inputs and instead spends its words on output content.

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

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

The description states a specific verb ('Get') and resource ('business tiers') and even enumerates the tier bucket values (MEI, small, medium, large). It is clearly distinguishable in subject matter from the sibling tools (calculate_cost, compare_brands, get_brands), though it never explicitly contrasts itself with them.

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

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

There is no statement of when to use this tool versus the siblings, no prerequisites, and no exclusions. The agent must infer that this is a reference lookup for tier definitions while get_brands covers brand data.

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