eGestor MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing that it writes data, is non-idempotent, will produce duplicate contacts on repeat calls, returns the new code, and maps to POST /v1/contatos.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the action, immediately followed by the most consequential behavioral fact (non-idempotent) and the return value. Zero filler.

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 supplies the return value ('the new code'), and the schema fully covers the 10 input parameters. Everything needed to call and interpret the result is present.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented in the schema. The description adds no parameter-level meaning (e.g., that tipo accepts multiple kinds, or CPF/CNPJ formatting), 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 (create) and resource (contact), names the entity subtypes in parentheses, and is unambiguously the write counterpart to egestor_get_contact and egestor_list_contacts.

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 non-idempotency warning ('calling it twice creates two contacts') gives real usage guidance for a create tool. It stops short of explicitly routing the agent to egestor_list_contacts to check for duplicates first, which is the natural alternative for a non-idempotent operation.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the upstream endpoint (GET /v1/empresa) and the token-scoping rule, which is useful context, but says nothing about what happens on an invalid/expired token or how errors surface.

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 short sentences with zero waste; the core purpose is front-loaded and the API reference is appended as a compact secondary detail.

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

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

For a no-parameter read tool with readOnlyHint set and no output schema, the description gives enough: what is fetched, whose data it is, and the underlying endpoint. A brief note on what 'registration data' includes or the error behavior would close the remaining gap.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly adds no parameter claims, and the token-scoped nature implicitly explains why no identifier argument is needed.

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

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

States a specific verb ('Get') and resource ('registration data of the company'), plus a meaningful scope qualifier ('that owns the token'). No sibling tool covers company data, so the resource alone distinguishes it from the contact/payable/sale tools in the sibling 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 token-ownership scoping implies the usage context (fetch the authenticated account's company profile), but there is no explicit when-to-use or when-not guidance and no mention of alternatives. Usage is inferable rather than 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?

readOnlyHint=true already declares the safety profile, so the description's main addition is the underlying REST endpoint, which helps with error mapping. It says nothing about what happens with an invalid or unknown code (404 behavior) or the shape of 'full 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?

Two short sentences with zero padding; the purpose is front-loaded and the endpoint reference is a compact secondary detail.

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

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

For a single-parameter read tool with readOnlyHint and no output schema, this is nearly complete. The only gap is that 'full data' is undefined and error behavior for a bad code is unstated.

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 single parameter already documents that the code comes from the matching list tool. The description's 'by code' merely restates this, adding no format or constraint detail 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?

States a specific verb and resource ('Get full data of one contact') and the retrieval key ('by code'), which distinguishes it from the sibling list tools. It doesn't name egestor_list_contacts explicitly, but 'one contact' versus a list is 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 gives no when-to-use guidance or alternatives; it never says to use egestor_list_contacts first to obtain the code. The only hint that a prior list call is needed lives in the schema's parameter description, not the tool description.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description's addition is the raw endpoint mapping (GET /v1/pagamentos/{codigo}), which is mild context but says nothing about failure behavior for a nonexistent code or the shape/size of the response.

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 short sentences, zero filler, with the core action front-loaded ahead of the endpoint detail. Nothing needs trimming.

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 is the only place an agent could learn what a payable record contains, and it says nothing about the returned fields or not-found handling. For a simple read-by-id tool that is a tolerable gap, but it is still the weakest part of an otherwise adequate definition.

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 single 'codigo' parameter is fully documented in the schema, including its constraint (integer > 0) and its origin. The description adds no format, sourcing, or example detail beyond that, 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 names a specific verb and resource ('Get one payable by code'), which cleanly separates it from the list-style siblings such as egestor_list_payables. It stops short of explicitly naming that sibling, but the singular/plural contrast makes the distinction inferable.

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 only implied: 'by code' signals a single-record lookup, but the description never states when to use this instead of egestor_list_payables or what to do if the code is unknown. The 'from the matching list tool' hint lives in the schema, not the description, so no exclusions or preconditions are offered here.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the concrete API mapping (GET /v1/produtos/{codigo}), which confirms it is a plain read, but says nothing about what 'full data' includes, whether related entities are embedded, or how a missing code is handled.

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 compact sentences, with the operation and scope front-loaded and the endpoint mapping as supporting detail. 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?

For a single-parameter read-only getter this is close to sufficient, and annotations carry the safety profile. But 'full data' is undefined and there is no output schema to compensate, so an agent cannot anticipate the response shape or whether nested product data is included.

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% and the single parameter already documents itself as 'The record code (from the matching list tool).' The description's 'by code' restates the schema without adding format, range, or lookup-source detail, 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 and resource ('Get full data of one product by code'), which is enough to tell it apart from egestor_list_products and egestor_list_services, which return collections rather than a single record. It never names a sibling explicitly, so differentiation is implied rather than stated.

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?

'Get full data of one product by code' implies the usage pattern (fetch a single record's details, presumably after finding the code in a list), and the schema note 'from the matching list tool' reinforces that. However, there is no explicit when-to-use/when-not guidance and no mention of error behavior for an unknown code.

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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered, and the description adds the concrete REST endpoint GET /v1/compras/{codigo}. It says nothing about error behavior (e.g., unknown code) or what "full data" comprises, so it adds only modest context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two terse sentences with the core action front-loaded and the endpoint as a compact secondary detail. Nothing extraneous.

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

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

For a single-parameter read tool with readOnlyHint annotations and full schema coverage, the description supplies enough to call it correctly. The only minor gap is not clarifying what fields "full data" returns, though no output schema exists to govern that.

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

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

Schema coverage is 100% and the single parameter is documented as the record code sourced from the matching list tool. The description adds no format, range, or sourcing detail beyond what the schema already provides, so 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?

"Get full data of one purchase" states a specific verb and resource, and the singular "one purchase" implicitly contrasts with the list_purchases sibling. It does not explicitly name that sibling, so it falls short of the top tier.

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 schema note "from the matching list tool" implies you first call egestor_list_purchases to obtain the code, which is useful implicit routing. There is no explicit when-to-use/when-not statement or named alternative in the description itself.

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?

The description's 'Get' and the underlying GET endpoint are consistent with readOnlyHint=true, so no contradiction. It adds the raw API path, which is modest context, but says nothing about error behavior, not-found handling, or what the payload contains beyond the inferred record.

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 short sentences, front-loaded with the purpose. The API path sentence is of marginal value to an agent but does no harm and is compact.

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 one-parameter read tool with annotations covering safety, the essentials are present. However, with no output schema, the description gives no indication of what a receivable record contains or how a missing code is handled, leaving a real gap.

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 single 'codigo' parameter is already documented in-schema, including the note that it comes from the matching list tool. The description's 'by code' restates the schema rather than adding format or validation detail, 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?

The description states a specific verb and resource ('Get one receivable by code'), which cleanly separates it from the sibling list tool egestor_list_receivables. It doesn't explicitly name the sibling, but the singular-noun phrasing makes the distinction implicit.

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 rather than stated: retrieving a single record by code, with the code conceptually coming from a list call. There is no explicit 'use this when…' or 'do not use for…' guidance, and no mention of what to do if the code is unknown.

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?

The readOnlyHint annotation already establishes the safe read-only profile. The description adds useful behavioral context by identifying the API endpoint and summarizing the returned data (items, payments, totals), which matters because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with the core purpose and returned data front-loaded. Every phrase adds value and there is no filler.

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 read-only lookup with two fully documented parameters, the description covers the essential purpose, endpoint, and return content. It could be slightly richer about cancellation behavior or response shape, but it is adequate without an output 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%, so the parameters codigo and listarCanceladas are already documented. The endpoint path with {codigo} loosely reinforces that codigo identifies the sale, but the description adds no new parameter 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 states a specific verb and resource: get full data of one sale. It distinguishes from the sibling list tool by emphasizing a single sale and detailing the returned data categories (items, payments, totals).

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 to retrieve one sale's complete record after obtaining its code. There is no explicit guidance about when not to use it or a named alternative such as egestor_list_sales.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the upstream endpoint mapping (GET /v1/disponiveis), which is mildly useful for traceability but discloses no behavioral traits such as pagination limits, auth requirements, or what an account record contains.

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 short sentences with the resource definition front-loaded; nothing is buried. The second sentence is largely a restatement of the endpoint slug and earns only marginal space.

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

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

For a simple optional-parameter list tool the description is serviceable, and the schema covers the inputs. With no output schema, however, the description leaves the shape of a returned account record entirely unexplained, which an agent must guess before using the results.

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

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

Schema description coverage is 100% and all three parameters (page, filtro, orderBy) are documented inline, so the baseline of 3 applies. The description contributes nothing beyond the schema, notably not explaining what fields 'filtro' searches over for this particular resource.

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 (List) and a precisely qualified resource: 'cash boxes and bank accounts (disponiveis)'. The parenthetical disambiguates 'accounts' from the sibling egestor_list_users, and no other sibling lists financial accounts, so the tool is trivially distinguishable.

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 explicit when-to-use or when-not-to-use statement, but usage is implied unambiguously because no sibling exposes this resource. For a single-purpose read-only list endpoint, the absence of exclusions costs little, yet the description still adds nothing about prerequisites or alternatives.

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?

The readOnlyHint annotation already establishes the safety profile, and the description adds only the raw endpoint path (GET /v1/categorias), which is not behavioral context. Nothing is said about pagination defaults, result volume, or whether categories are flat or hierarchical, even though the schema hints at 50 rows per page.

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 short sentences, front-loaded with the purpose, with no filler. The endpoint reference is of marginal but non-zero value, so it does not quite reach a 5.

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 read-only list tool with no required params and no output schema, this is minimally adequate. It leaves open what a category record contains and how pagination should be traversed, which matters for an agent that needs to enumerate all categories.

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

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

With 100% schema description coverage, the schema already documents page, filtro, and orderBy adequately. The description contributes nothing extra about these parameters, 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+resource ('List product and finance categories'), which is enough to distinguish it from the sibling list tools covering contacts, products, sales, etc. It also names the underlying endpoint, but does not clarify scope beyond that one line.

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 alternatives, no prerequisites, and no exclusions. The agent must infer that this is the lookup path for category IDs used by other endpoints.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/contatos) and frames the tool as a discovery entry point, but says nothing about result volume, pagination behavior, or empty-result handling beyond what the schema states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, with the core resource definition front-loaded before the usage hint and the endpoint reference. Nothing here is redundant with structured fields in a wasteful way.

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

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

For a zero-required-parameter, read-only list tool with a fully documented schema and no output schema, the description covers purpose, entry-point role, and data source. It could say slightly more about what a result row contains (codes and names) but nothing essential to correct invocation is missing.

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 every parameter (page, tipo, fields, filtro, orderBy) is already documented in the schema. The description adds no syntax or format detail for any of them; the reference to 'finding a contact code' only loosely gestures at the filtro parameter.

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 ('List') and resource (contacts), then enumerates the domain subtypes it covers (customers, suppliers, carriers). An agent can distinguish it from egestor_get_contact (single record) by the verb alone, though no sibling is named 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?

'Good first call to find a contact code' gives concrete sequencing guidance — use this to discover codes, then presumably follow up with egestor_get_contact. It stops short of naming that alternative or stating exclusions, so it is clear context rather than full routing.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description need only add context; it contributes the endpoint identity and status-code semantics, which is modest added value. It says nothing about page size limits, ordering defaults, or response shape beyond what the schema already declares.

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 compact sentences, front-loaded with the resource and scope. The trailing API endpoint reference is mildly redundant metadata but still earns its place for traceability.

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 leaves the returned payload entirely unspecified – an agent cannot tell which fields a payable row exposes or how status values appear in results. For a six-parameter list tool this is adequate but not 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 description coverage is 100%, so the schema already documents page, dtIni, dtFim, filtro, orderBy, and situacao. The description's 10=open / 30=paid gloss merely repeats the schema's situacao description, adding no syntax or format detail beyond 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?

States a specific verb and resource ("List accounts payable") plus the underlying API endpoint GET /v1/pagamentos, and decodes the situacao values inline. It implicitly separates itself from egestor_get_payable (singular) and egestor_list_receivables through the resource name, but never explicitly names 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?

The date-range filtering and status codes hint at how to use it for open-vs-paid queries, but there is no explicit guidance on when to pick this over egestor_get_payable for a single record, nor on pagination strategy or prerequisites.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results include prices and stock data and names the underlying API endpoint, but says nothing about pagination totals, result limits, or empty-result behavior beyond what the schema implies.

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 compact sentences with the capability front-loaded; the API endpoint reference is short and mildly useful for traceability. Nothing is bloated, though the endpoint sentence contributes little to tool selection.

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?

This is a simple read-only listing tool with fully documented parameters and a readOnlyHint annotation, so the burden is low. The description covers return content at a high level (prices and stock data), which is reasonably complete given there is no output schema; only deeper return-shape detail is missing.

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 page, fields, filtro, and orderBy all documented in the schema. The description adds no parameter-level semantics such as valid field names for 'fields' or supported sort fields for 'orderBy', so the 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?

Uses a specific verb ('List') and resource ('products') and adds what each record carries (prices and stock data), which is more than a restatement of the name. It does not explicitly contrast with the sibling egestor_get_product, so the list-vs-single distinction is implied rather than stated.

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 list semantics make the basic use case clear by implication, but there is no guidance on when to use this versus egestor_get_product or the other list endpoints, and no mention of how filtering (filtro) or paging should drive selection. Adequate but leaves the agent to infer routing.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST endpoint and the situacao code meanings, but says nothing about pagination behavior beyond what the schema states, or about what a returned record looks like.

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 compact clauses, front-loaded with the action and its key filter, followed by a short provenance note on the endpoint. No filler, though the endpoint reference is arguably optional detail for an agent choosing a tool.

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

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

For a read-only list tool with nine optional params and no output schema, the description does not indicate the shape of returned purchase records or that results are paginated 50-per-page. The schema carries parameter detail, so this is adequate but leaves the return side unexplained.

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

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

Schema description coverage is 100%, so all nine parameters are already documented with formats, enums, and defaults. The description restates the situacao codes (10/50) and date-range filtering, adding no semantics beyond the schema — 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+resource ('List purchases') and adds scope ('filterable by date range') plus the underlying endpoint GET /v1/compras. It is clearly distinguishable from the singular egestor_get_purchase sibling, though it never names that sibling 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?

The date-range filtering and the status codes hint at when this tool applies, but there is no explicit guidance on when to use it versus egestor_get_purchase or egestor_list_payables, and no exclusions or prerequisites.

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?

readOnlyHint=true already declares this is a safe read, so the description's bar is lower. It adds useful context (the underlying GET /v1/recebimentos endpoint and what status 20/40 mean), but says nothing about pagination limits, total counts, or empty-result behavior beyond what the page parameter schema already states.

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 short sentences with no waste — the core action and its filters come first, followed by the endpoint reference. Every element 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?

For a read-only list tool with fully documented parameters and no output schema, the description covers purpose, filtering, and data source adequately. It stops short of describing the shape of returned receivables or default sort behavior, a minor gap given no output schema exists to carry that.

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

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

Schema description coverage is 100%, so all six parameters (page, dtIni, dtFim, filtro, orderBy, situacao) are already documented in the schema. The description's parenthetical about 20=open/40=received merely restates the situacao schema description, adding no new semantics; 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 and resource ("List accounts receivable") plus its status-code semantics and date-range filtering. It is clearly distinguishable from the singular egestor_get_receivable in concept, but it never names the sibling or clarifies the list-vs-get split, so it falls short of a 5.

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

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

The description implies when this tool is used (browsing receivables within a date range) and explains the situacao filter values. However, it gives no explicit guidance on when to use egestor_get_receivable versus this list tool, or when to prefer the payables counterpart, so usage is left to inference.

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?

readOnlyHint=true already declares this is a safe read, so the description needn't restate safety. It adds useful context — the underlying endpoint GET /v1/vendas and the meaning of status values — but says nothing about result volume, pagination behavior, or what happens when filters match nothing.

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 compact clauses front-loaded with the verb and resource, followed by the endpoint reference. Nothing wasted; the status legend is the only element that arguably duplicates schema 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 9-optional-param, read-only list tool with no output schema, the description plus full schema coverage gives an agent enough to call it correctly. The remaining gap is not naming sibling alternatives (get_sale) or summarizing the returned record shape.

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%; every one of the 9 parameters is documented in the schema, including the situacao enum. The description's situacao legend and mention of date/contact filtering largely duplicate the schema, so baseline 3 applies rather than added 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?

Specific verb+resource (list sales) with the status-value legend (10=quote, 50=sale) that clarifies what 'sales' includes. It doesn't distinguish itself from the sibling egestor_get_sale, so an agent must infer list-vs-single-record on its own.

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

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

It states what can be filtered (date range, contact) so usage is implied, but there is no explicit 'use this when you need the collection, use get_sale for one record' routing. Alternative tools such as egestor_get_sale are never mentioned.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying API endpoint but does not disclose pagination behavior, rate limits, or return characteristics beyond what the schema and annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with the purpose front-loaded and no wasted prose. The API endpoint reference is compact and useful for technical 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?

For a simple read-only list tool with complete parameter documentation and read-only annotations, the description is nearly sufficient. It does not mention return shape or whether inactive services are included, but no output schema exists and the core purpose 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?

Schema description coverage is 100%, so all three parameters are fully documented in the schema. The description adds no additional parameter meaning, which is acceptable given the schema's completeness.

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

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

The description states a specific verb and resource: list services the company sells. It is easily distinguished from sibling tools such as list_products or list_contacts by the resource being listed.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is only implied by the tool name and description.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds only the endpoint mapping and the fact that results are scoped to the account; it says nothing about pagination behavior, result volume, or ordering defaults beyond what the schema already carries.

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 short, front-loaded sentences with the resource scope first. The trailing endpoint-reference sentence is mildly redundant plumbing but is short and aids traceability, so it mostly 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?

For a simple, zero-required-parameter read tool with a fully documented schema and annotations covering safety, the description is largely sufficient. Minor gap: with no output schema, it does not hint at the shape of returned user records or how the sales-person subset differs.

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% (page, fields, filtro, orderBy, vendedor are all documented in-schema), so the schema carries the burden. The description adds no extra meaning such as which fields are filterable via `filtro` or what `fields` accepts — 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 and resource ("List users and sales people of the account") plus the underlying endpoint, so the agent knows exactly what it returns. It is clearly distinct from the other list_* siblings by resource, but never names or contrasts them 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 only: it is a read/list tool for user and sales-person records. There is no statement of when to prefer this over egestor_list_contacts or other list tools, and no prerequisites (e.g. auth scope, that it is account-scoped) are spelled out.

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