feriadosapi-mcp

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

With no annotations provided, the description carries full burden and successfully discloses that the tool returns a 'lista paginada' (paginated list) and details the return fields (nome, data DD/MM/YYYY, tipo, descrição, indicador bancário FEBRABAN). It lacks rate limit or authentication details, but covers the essential behavioral traits for a read operation.

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

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

Four sentences efficiently structured: purpose (1), usage context (2), filter capabilities (3), alternatives and return format (4). Every sentence provides unique value with no redundancy or filler. Information is front-loaded with the core 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?

Despite lacking an output schema, the description verbally documents the return structure and pagination behavior. Given the tool's complexity (7 optional parameters, multiple filter combinations), it adequately covers operational context, though it could specify default page sizes or maximum result limits.

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%, establishing a baseline of 3. The description enumerates the filterable fields (data, tipo, estado, cidade, ano, mês) but does not add semantic meaning beyond what the schema already provides. It does not clarify the relationship constraints (e.g., month requiring year) which are only in the schema.

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

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

The description opens with 'Busca feriados brasileiros com filtros flexíveis,' providing a specific verb (search), resource (Brazilian holidays), and distinguishing capability (flexible filters). It clearly differentiates from siblings by contrasting 'consultas gerais' with 'tools especializadas' like feriados_nacionais and feriados_por_estado.

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 when-to-use guidance ('para consultas gerais quando precisar filtrar por múltiplos critérios') and explicit when-not-to-use with named alternatives ('Para buscas mais específicas, prefira usar as tools especializadas'). This creates clear selection criteria against the seven sibling tools.

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 provided, the description carries the full burden and successfully discloses the return structure (nome, UF, código IBGE) and scale (5.500 municípios), implying pagination needs. However, it lacks explicit mention of error states (e.g., invalid UF) or rate limiting.

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?

Four tightly constructed sentences with zero waste: purpose/returns, workflow integration, filtering capability, and performance guidance. Information is perfectly front-loaded and every sentence 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 the lack of output schema, the description appropriately documents return values. It provides sufficient context for the 3-parameter tool with clear schema coverage and workflow relationships. Minor gap: pagination behavior is only implied by the 5,500 count warning rather than explicitly stated in the prose.

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%, establishing a baseline of 3. While the description reinforces the UF parameter's purpose for filtering, it does not add significant semantic details, syntax examples, or validation rules 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?

The description opens with a specific verb ('Busca') and resource ('municípios brasileiros'), explicitly states return values ('Retorna nome, UF e código IBGE'), and clearly distinguishes itself from sibling holiday tools by positioning itself as a prerequisite step for 'feriados_por_cidade'.

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 workflow guidance ('Use esta tool para descobrir o código IBGE... antes de consultar feriados municipais com feriados_por_cidade'), names the specific sibling tool to use next, and gives practical filtering advice ('use o filtro de UF para resultados mais precisos') due to the large dataset size.

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 provided, the description carries the full burden. It successfully discloses content scope (nacionais + facultativas) and legal basis, but omits operational details like rate limits, pagination behavior, or response structure that would be necessary for 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?

Four tightly constructed sentences with zero waste: purpose/legal basis, content details, use case, and filtering capabilities. Information is front-loaded and every sentence 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 the 4 optional parameters and read-only nature, the description adequately covers the tool's scope and functionality. Minor deduction for lacking output format description (no output schema exists), though the content of the return is well-characterized.

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% description coverage, establishing a baseline of 3. The description reinforces the filtering concepts (UF/IBGE) and explains what 'facultativos' entails via specific holiday examples, but does not add significant semantic detail beyond the well-documented 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 specific action 'Lista' and resource 'feriados bancários do calendário oficial FEBRABAN', distinguishing it from siblings via the specific legal reference (Resolução 4.880/2020) and explicit enumeration of included facultative dates (Carnaval, Quarta-feira de Cinzas, etc.).

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 clear usage context ('Ideal para cálculos de vencimentos, compensações e prazos bancários') and explains filtering capabilities, but lacks explicit guidance on when to prefer siblings like 'feriados_nacionais' or 'verificar_dia_util_bancario' over this comprehensive 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?

No annotations provided, so description carries full burden. Adds valuable behavioral context about returning all available years when 'ano' is omitted. However, omits read-only/safety status, rate limits, and crucially lacks any description of the return data structure (array of objects, fields, etc.) given the absence of an 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?

Four well-structured sentences front-loaded with primary purpose. Each sentence serves a distinct function: scope definition, examples, optional features, and default behavior. Only minor deduction for not mentioning the 'bancarios' parameter which exists in the schema.

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?

Adequate for input handling with 3 optional parameters, but incomplete regarding output expectations. Without an output schema, the description should describe the returned data format (e.g., 'returns array of holiday objects with date and name fields'), which is absent.

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% for all 3 parameters, establishing baseline 3. Description reinforces 'facultativos' by listing examples (Carnaval, Corpus Christi) and clarifies 'ano' default behavior, but does not add significant semantic depth 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?

Opens with specific verb 'Lista' and clear resource 'feriados nacionais do Brasil'. The explicit enumeration of included holidays (Carnaval, Tiradentes, etc.) concretely defines scope, distinguishing it from siblings like feriados_por_estado or feriados_bancarios.

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 implicit usage context by describing default behavior when 'ano' is omitted and when to use 'facultativos'. However, fails to address the 'bancarios' parameter's existence or clarify when to use this parameter versus the dedicated 'feriados_bancarios' sibling 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?

No annotations provided, so description carries full burden. It discloses critical behavioral trait: the aggregation logic combining three jurisdictional levels (national+state+municipal). Missing: explicit read-only declaration, rate limits, or return format details, though 'Lista' implies read-only.

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 well-structured sentences: purpose/scope, usage condition, prerequisites/examples. Zero redundancy; every sentence earns its place with specific actionable 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 4-parameter tool with complete schema coverage, description adequately covers purpose, scope differentiation, and workflow. Minor gap: no output format description (though none required given no output schema exists, mentioning return structure would strengthen 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?

Schema has 100% coverage (baseline 3), but description adds substantial value with concrete IBGE code examples (São Paulo = 3550308, etc.) and workflow guidance referencing buscar_municipios that isn't in the schema descriptions.

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 specific action 'Lista todos os feriados' and resource 'cidade brasileira', explicitly distinguishing scope from siblings via '(feriados nacionais + estaduais + municipais)'—clearly differentiates from feriados_nacionais and feriados_por_estado.

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 when-to-use ('quando o usuário perguntar sobre feriados em uma cidade específica'), mandatory prerequisite ('Requer o código IBGE'), and directly names alternative tool ('use primeiro a tool buscar_municipios').

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 full burden. It explains the aggregation logic (national + state holidays) and parameter behaviors (banking holiday filter), but fails to disclose read-only nature, output format/structure, or error handling (e.g., invalid UF behavior) that would be essential for a tool without annotation hints.

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

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

Three well-structured sentences: purpose statement, usage trigger with examples, and valid value enumeration. Every sentence earns its place. The UF list, while long, is necessary reference data rather than verbosity. Information is front-loaded with the core purpose first.

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 lack of output schema and annotations, the description adequately covers the required parameter domain (UF values) and filtering logic. However, it could improve by describing the return structure (e.g., 'returns array of holidays with date, name, and type') to fully compensate for the missing output specification.

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?

Despite 100% schema description coverage (baseline 3), the description adds substantial value by enumerating all 27 valid UF acronyms ('AC, AL, AP...'), which compensates for the lack of an enum constraint in the schema. This specific value list is critical for correct invocation and goes well beyond the schema's generic 'Sigla do estado' 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 uses a specific verb ('Lista') with clear resource ('feriados de um estado brasileiro') and precise scope ('feriados nacionais + estaduais daquele UF'). It effectively distinguishes from siblings like feriados_nacionais and feriados_por_cidade by explicitly stating it aggregates both national and state-level holidays.

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 when-to-use guidance with concrete examples ('feriados em São Paulo', 'feriados do RJ'). While it clearly indicates the tool is for state-specific queries, it does not explicitly name sibling alternatives (e.g., 'use feriados_por_cidade for municipal holidays'), though the scope description implicitly guides selection.

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 provided, so description carries full burden. It discloses return format ('Retorna sigla (UF) e nome completo'), but omits details like data freshness, caching, or whether territories are excluded.

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 sentences with zero waste: first defines action/scope, second defines usage trigger, third defines return value. Front-loaded and efficient.

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 reference tool with no input schema, description adequately compensates by specifying exact count (27), inclusion of DF, and return fields. Lacks output schema but describes return values textually.

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 present per schema. Description correctly implies no filtering is possible by stating it lists 'todos' (all) states, meeting the baseline for 0-param tools.

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 uses specific verb 'Lista' with exact resource scope '27 estados brasileiros (26 estados + Distrito Federal)' and distinguishes from holiday/municipality siblings by focusing on UF siglas.

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 when-to-use guidance ('Use quando precisar consultar as siglas... ou quando o usuário perguntar'), though does not explicitly mention sibling 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?

No annotations provided, so description carries full disclosure burden. It successfully explains return behavior (list of holidays), multiplicity (national + municipal possible), and empty list semantics (NÃO é feriado). Minor gap: no mention of date validation behavior or timezone handling.

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?

Four well-structured sentences front-loaded with purpose, followed by usage triggers, return format, and edge case handling. Zero redundancy; every sentence provides distinct value (purpose, examples, return structure, empty-list 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 simple single-parameter lookup tool with no output schema, the description adequately compensates by explaining return values (list of holidays) and interpretation (empty list = non-holiday). No significant gaps given the tool's low 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?

Schema coverage is 100% with complete description of 'data' parameter format (YYYY-MM-DD) and example. Description adds context that it's a 'data específica' but doesn't need to compensate for schema gaps since none exist. Baseline 3 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 opens with specific verb 'Verifica' and clear resource 'feriado no Brasil', explicitly scoping to Brazil. It distinguishes from sibling tools like 'buscar_feriados' and 'feriados_por_estado' by emphasizing specific date verification rather than range searches or bulk listings.

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 Portuguese usage examples ('amanhã é feriado?', '25 de dezembro é feriado?') that clearly signal when to invoke. Lacks explicit naming of sibling alternatives (e.g., when to use 'verificar_dia_util_bancario' instead), though the single-date focus implies the distinction.

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 provided, so description carries full burden. Discloses return structure (motivo + próximo dia útil) and data source specifics (FEBRABAN calendar including Carnaval, Quarta de Cinzas, etc.). Implies read-only nature via 'verifica' but doesn't explicitly state safety/idempotency.

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?

Four sentences with zero waste: purpose, usage triggers, output behavior, and data source. Every sentence provides distinct value. Well front-loaded with clear intent.

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

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

For a single-parameter query tool with no output schema, description fully compensates by detailing return values (reason codes, next business day) and business logic (FEBRABAN rules). No gaps remain.

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% description coverage for the single 'data' parameter (format YYYY-MM-DD). Description adds no additional parameter semantics, which is acceptable given complete schema documentation.

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 specific action (Verifica) + resource (dia útil bancário) + scope (agências abrem normalmente). Distinguishes from sibling 'verificar_data' by specifying banking context and FEBRABAN calendar.

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?

Explicit 'Use quando...' with concrete example queries ('o banco abre amanhã?', 'quando vence o boleto?'). Provides clear trigger conditions for selection over sibling tools.

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