scrypta-mcp-server

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

Annotations already declare readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description adds useful context beyond them by noting that results are paginated and what fields come back (nomes, preços, URLs), though it omits any note on default page size or empty-result behavior (the latter is covered by the schema).

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

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

Two short sentences: the first states the action, the second states filters and return shape. Front-loaded and free of filler, with nothing repeated from the title.

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 seven optional parameters, full schema coverage, annotations, and an output schema, the definition supplies what is needed to call it correctly. It is slightly thin on routing to siblings and on pagination defaults, but nothing critical 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 the baseline is 3. The description restates four of the seven parameters (name term, category, price range, in-stock) but adds no syntax or format detail beyond the schema, and never mentions limit/offset pagination controls.

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 ("Busca produtos no catálogo") and enumerates the filter facets it accepts, so the agent knows exactly what the tool does. It does not name or contrast with siblings like produtos_por_categoria or listar_categorias, so differentiation is left 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?

The phrase "Aceita filtros combinados" implies this is the general-purpose filtered search, but there is no explicit when-to-use or when-not guidance versus produtos_por_categoria (already-filtered listing) or listar_categorias. Usage must be inferred from the parameter list 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?

Annotations already declare readOnlyHint, idempotentHint and a closed-world scope, so the safety profile is covered. The description contributes by signaling the response shape is an aggregate summary (counts, categories, price range) rather than a full listing, which helps set expectations, but adds no other behavioral context.

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

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

A single front-loaded sentence with no filler; the field enumeration is the substance and earns its space.

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

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

An output schema exists, so the return values need not be spelled out, and annotations carry the safety profile. For a zero-parameter read tool this covers what an agent needs, though it could note the overview-vs-listing relationship to siblings.

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

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

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies a no-argument call.

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 ('Retorna informações gerais sobre a empresa') and enumerates the returned fields (URL, total de produtos, categorias, planos, faixa de preço), which distinguishes it from the itemized siblings like buscar_produtos and listar_categorias. It never names a sibling explicitly, so differentiation is implicit 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 phrase 'informações gerais' hints this is the overview/aggregate entry point rather than a filtered listing, but the description never says when to call this instead of listar_categorias or listar_planos. Usage is inferable, not instructed.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description contributes the fact that results are aggregated with per-category counts, but says nothing about ordering, whether empty categories appear, or whether the catalogue is static (caching). Adequate but thin given annotations carry most of the load.

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 sentence that front-loads the verb and scope, with the one extra detail (per-category counts) placed where it is most useful. No filler to trim.

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

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

An output schema exists, so return-shape details need not be repeated, and annotations cover the read-only, idempotent nature. For a simple zero-param listing tool the description is sufficient, though a note on ordering or on how to follow up with produtos_por_categoria 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, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the call is argument-free by scoping the result to 'todas as categorias'.

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 ('Lista todas as categorias de produtos') and adds the meaningful detail that each entry includes a count ('com contagem por categoria'). It does not, however, distinguish itself from the sibling 'produtos_por_categoria', which an agent could easily confuse with it.

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 and no mention of the obvious alternative (produtos_por_categoria) for drilling into a single category's products. The agent must infer the workflow from the description alone; only the zero-parameter signature makes the intent relatively self-evident.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral detail — only published clients are returned — but says nothing about return volume, pagination, or whether unpublished clients can be retrieved at all.

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 short sentence with no filler, and the scope qualifier is placed where it belongs. It is arguably under-specified rather than over-long, but from a pure conciseness standpoint it wastes nothing.

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

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

For a zero-parameter, read-only listing tool with annotations and no output schema, the description is minimally sufficient to call correctly. It still leaves open what a 'cliente' record contains and how large the result set is, which matters for an agent deciding whether to call it.

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 the baseline of 4 applies; there is no parameter semantics for the description to explain. The 'publicados' filter is fixed rather than parameterized, which is consistent with the empty 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 ('Lista todos os clientes Scrypta') plus a scope qualifier ('publicados'), so an agent knows this returns the published client list. It does not, however, differentiate itself from the sibling listing tools (listar_categorias, listar_planos, buscar_produtos), relying on the tool name alone for that.

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

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

There is no guidance on when to use this versus buscar_produtos or the other listar_* siblings, and no exclusions or prerequisites stated. The agent must infer from the name that this is the client-listing tool.

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, idempotentHint, and openWorldHint=false, so safety behavior is covered. The description adds useful return-content context (prices, monthly/annual/trial periods, descriptions), but does not discuss pagination, filtering, or rate limits.

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 redundant or filler content. Every clause contributes to what is listed and what data is returned.

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-parameter, read-only listing tool with an output schema and clear annotations, the description provides enough context to call it correctly. No critical behavioral or usage information 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?

The tool has zero parameters, so there are no parameter semantics to explain. Baseline 4 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: listing all offered plans/subscriptions, including prices and billing periods. The resource is clearly distinct from sibling product/category tools, though it does not explicitly name them for 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?

Usage is implied by 'Lista todos' and the zero-parameter schema, but there is no explicit guidance on when to choose this tool over alternatives or whether filters exist elsewhere.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no note on pagination, result ordering, or what happens when the category name is not an exact match, which matters given the schema insists on 'Nome exato'.

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, appropriately sized for a one-parameter list tool. It is efficient but so terse that it leaves obvious questions unaddressed rather than spending a sentence to close them.

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

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

An output schema exists, so return values need not be explained, and the only parameter is fully documented in the schema. What remains missing is differentiation from buscar_produtos and any behavior around inexact category names, which an agent would need to call this correctly in a multi-tool environment.

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 is well documented in the schema, including the exact-name requirement and the listar_categorias prerequisite. The description itself adds no parameter meaning beyond restating the category filter, so the baseline of 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 ('Lista todos os produtos de uma categoria específica'), so the agent knows exactly what it retrieves. It does not, however, distinguish itself from the sibling buscar_produtos, leaving the agent to infer the boundary between listing by category and searching products.

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 contains no when-to-use or when-not-to-use guidance and never mentions buscar_produtos or listar_categorias as alternatives. The only prerequisite hint ('Use listar_categorias antes') lives in the schema property, not 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that retrieval is semantic rather than keyword-based and scoped to an internal article corpus, but says nothing about result count, ranking, or what a hit 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?

A single front-loaded sentence naming the action, the corpus and the topic scope, with no filler. It is efficient, though it stops short of covering return behavior.

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 semantic search with annotations covering safety, the definition is nearly sufficient, but with no output schema the description should say something about what comes back (article excerpts, links, scores) and any limits. That gap keeps it at minimum-viable rather than 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?

Only one parameter exists and schema description coverage is 100%, with examples already given in the schema ('MCP', 'GEO', 'agentic commerce'). The description adds nothing about query construction, natural-language vs keyword phrasing, or length, 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?

States a specific verb ('busca semântica') and resource ('Super Artigos / Hubs de Conhecimento da Scrypta') plus the topical domain (GEO, MCP, Agentic Commerce). This clearly separates it from the sibling tools, which all deal with products, categories, clients or plans rather than articles.

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 the topical scope: an agent can infer it should call this when the question concerns GEO, MCP or Agentic Commerce. There is no explicit when-to-use statement, no guidance on phrasing the query, and no mention of what to do when the topic falls outside these hubs.

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