Observatório BR

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

Annotations already declare it as a safe, idempotent read, and the description adds substantial behavioral context beyond them: missing periods return null, units/frequencies accompany the data, a warning is emitted when a series starts after `from`, and dataStatus reports per-code states. That is exactly the output-behavior disclosure an agent needs since no output schema exists.

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 front-loaded sentences, each carrying a distinct fact (constraint, null semantics, units/frequencies, warning/dataStatus). Dense but no filler; could be marginally tightened by grouping the return-value sentences.

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 covers the return shape (units, frequencies, warning, dataStatus) well. It does not explain failure behavior for codes without series beyond 'só aceita', which would complete the picture.

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 codes, from/to formats, and maxPoints bounds documented there. The description reinforces the code-count constraint and the meaning of `from` via the warning behavior, but adds little about maxPoints. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (aligns) and resource (2–6 series over a period for side-by-side comparison), immediately distinguishing it from the single-series sibling get_indicator_series. The 2–6 constraint is embedded in the purpose itself.

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

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

"Só aceita indicadores com hasSeries=true" gives a clear precondition/exclusion, so the agent knows when the tool will reject input. It does not explicitly route to get_indicator_series or other alternatives for non-series data, but the usage context is clear.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the no-slug default resolves to the most recent edition, and the returned text is site analysis that must be cited as such — an attribution constraint an agent would not otherwise know.

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, front-loaded with the core action, then the default behavior, then the citation obligation. No filler and nothing repeated from structured fields.

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-optional-parameter read tool with full annotation coverage and no output schema, the description covers the action, the default resolution path, and the citation requirement. An agent has everything needed to invoke it correctly and use the result.

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 with its origin (list_bulletins or search). The description still adds value by explaining what a null/absent slug means (return the latest edition), which the schema's 'default: null' does not spell out.

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: returns the full text of a published edition of the Weekly Bulletin. This makes it distinguishable from list-type siblings by the word 'texto completo', but it never names list_bulletins or search as the way to obtain a slug, leaving sibling routing to inference.

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?

'Sem slug, devolve a edição mais recente' tells the agent what happens with the only optional parameter, which implicitly guides the common case. However, there is no explicit statement of when to call this versus list_bulletins, or that a slug should be sourced from a listing/search call first (that hint lives only in the schema).

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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is fully covered. The description still adds value by disclosing that the response includes related indicators alongside the definition — relevant since 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?

A single front-loaded sentence with the resource stated first and illustrative examples at the end; there is no filler. The nested quotation marks around Portuguese terms make it slightly less clean to parse but not wasteful.

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 single-parameter lookup with no output schema, the description tells the agent what comes back (definition plus related indicators) and what the input represents. A note on behavior for unknown slugs 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?

Only one parameter, and the schema already documents it at 100% coverage including its provenance (list_concepts or search). The description's examples clarify what kind of term a concept is but add no slug format or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Devolve a definição de um conceito econômico do glossário') with two concrete examples, making the lookup-by-slug nature unambiguous. It stops short of explicitly contrasting with list_concepts/search, which are the lookup paths that produce the slug.

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: the examples and the slug parameter make it clear this is the detail-fetch step. The routing hint ('vindo de list_concepts ou search') lives in the schema, not the description, so no explicit when-to-use guidance is offered in the prose.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful fallback behavior ('Sem slug, devolve a mais recente'), but does not explain error handling, output shape, or what happens with invalid slugs.

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

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

The description is short and front-loaded, with the core behavior stated first. The second sentence about conceptSlug is less clearly connected to the tool's actual input, but overall the definition remains 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 simple read operation with one optional parameter and full schema coverage, the description provides enough context to call it correctly. The only notable gap is the ambiguous conceptSlug reference, which does not map to any input field.

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

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

Schema coverage is 100%, so the slug parameter is already documented. The description adds the valuable default behavior when slug is absent, but the mention of 'conceptSlug' is confusing because no such parameter exists in the input 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: 'Devolve o texto completo de uma pílula publicada.' It also clarifies default behavior when no slug is supplied. It does not explicitly contrast itself with list_daily_posts or search, so it is clear but lacks sibling 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?

It gives one concrete usage rule: without a slug it returns the most recent pílula. However, it does not say when to use this tool instead of list_daily_posts or search, nor does it explain how to obtain a valid slug beyond the schema note.

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 cover read-only/idempotent safety, so the bar is lower, yet the description adds genuinely non-obvious behavior: responses over 40k characters return a null payload with the beginning of the JSON in payloadPreview. Combined with the hasDetails precondition, this is exactly the operational context an agent needs.

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 dense sentences, no filler: what it returns, when it applies, and the truncation edge case. The precondition and content description are front-loaded before the caveat.

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?

No output schema exists, but the description compensates by naming the payload contents and the payloadPreview fallback, so return shape is clear. For a single-resource read tool with a documented precondition and truncation rule, nothing essential 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 coverage is 100%, so code/from/to formats are already documented. The description does not clarify whether from/to scope or filter the panel contents, which is the one semantic question an agent might have; baseline 3 applies when the schema does the heavy lifting.

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 (devolve) and resource (payload rico do painel de um indicador) with the exact content returned (KPIs, aberturas, resultados de modelo) and maps it to the underlying endpoint. This clearly separates it from siblings like get_indicator_series or get_indicator_latest without needing to open a schema.

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?

Gives an explicit precondition: only for indicators with hasDetails=true, which is the key gate for calling this tool. It does not name the alternative to use for indicators without details (e.g. get_indicator_series), so the agent must infer the fallback, keeping it below a 5.

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 readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the search window adapts to periodicity to tolerate publication lag, and the 'defasado' status flags stale data. This caveat is material for correct agent behavior.

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

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

Front-loads what is returned, then adds the periodicity/lag caveat and the dataStatus instruction. Three tight sentences with no filler, though the dataStatus note is slightly tacked on at the end.

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 carries the burden of explaining return values and does so (last value, previous, difference, period, unit, source), plus the dataStatus semantics. Complete enough to call and interpret results without further docs.

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, documented at 100% coverage in the schema with an example ('ipca'). The description adds no syntax or format detail beyond the schema, so it sits at the baseline for a fully documented single 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 and resource ('devolve o último valor disponível de um indicador') and enumerates the returned fields (valor anterior, diferença, período, unidade, fonte). It is clear what the tool does, though it does not explicitly contrast itself with siblings like get_indicator_series or get_indicator_details.

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?

Implicitly scopes usage to when the agent needs only the latest point, and gives an operational instruction to warn the user when dataStatus is 'defasado'. It never explicitly states when to prefer this over get_indicator_series or other indicator siblings.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real substance: 5-year default window, downsampling to maxPoints with the most recent point always preserved, window-only filtering, the 'note' warning when the source starts after the requested from, and the three dataStatus values plus what the agent should tell the user when data is not 'ok'.

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?

Front-loaded with the core behavior, then defaults, then downsampling, then dataStatus/note semantics — a logical order with no filler sentences. Dense but each sentence carries distinct information; only the final dataStatus sentence is slightly compressed into a run-on.

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 carries the burden of explaining returns and does so: period/value points, dataStatus enum values, and the 'note' field's purpose and expected use. Nothing essential for calling or interpreting the result 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 coverage is 100%, so the baseline is 3, but the description adds meaning not present in the schema: the default is described in terms of a 5-year window rather than just 'optional', and maxPoints is explained as spaced downsampling that preserves the latest point. It does not add format examples beyond the schema's YYYYMM, which is already documented.

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 ('Devolve a série temporal de um indicador') and even names the return shape (pontos period/value). It implicitly separates itself from get_indicator_latest and compare_indicators by scoping to a single indicator's series over a window, but never names or contrasts those siblings explicitly.

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

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

Useful behavioral context is given (omitting from/to yields the last 5 years), which effectively describes a default usage mode. However, there is no explicit when-to-use versus get_indicator_latest, compare_indicators, or get_indicator_details, leaving the agent to infer selection from tool names.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered; the description instead contributes substantive detail about what the returned content actually contains (formulas, sources, simplifications, limitations). This is genuinely useful for a retrieval tool with no output schema, though it says nothing about behavior for an invalid or missing slug.

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

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

One sentence, front-loaded with the action and resource, followed immediately by the content enumeration. Nothing is wasted and nothing important is buried.

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 one-parameter read tool with rich annotations and no output schema, the description covers what is returned and therefore what the agent can do with the result. It could be slightly stronger by naming the prerequisite producer tools, but no essential 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?

There is a single parameter with 100% schema description coverage, and the schema already explains where the slug comes from (list_methodology or search). The description adds no further meaning about slug format or validation, 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?

The description names a specific verb ("Devolve o texto completo") and resource ("artigo de metodologia") and enumerates the payload (fórmulas, fontes, simplificações, limitações). This clearly distinguishes it from the sibling list_methodology, which merely lists articles rather than returning their contents.

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: an agent can infer it should read an article after finding a slug, but the description itself never states when to use this versus list_methodology, search, or get_indicator_details. The routing hint ("vindo de list_methodology ou search") lives only in the schema's slug description, not in 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 read-only, idempotent, non-destructive behavior, so the description adds value by explaining what each mode returns: latest indicator values in listing mode, and series with up to 240 points plus min/max/average in detail mode. It does not mention pagination, errors, or permissions, but the return behavior is well disclosed.

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 compact and front-loaded, using two clear conditional clauses to explain the no-sectionId and with-sectionId cases. Every sentence carries useful information with 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?

With no output schema and only one optional parameter, the description is complete enough: it explains both modes, what the listing contains, what the detailed section contains, and the 240-point limit per indicator. An agent has enough information to choose the right call and interpret the result.

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 schema already documents sectionId as optional and sourced from the listing without sectionId. The description adds meaningful semantic context by explaining how the presence or absence of sectionId completely changes the response shape.

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 verb and resource, and it explicitly distinguishes the two modes: listing panorama sections without sectionId versus returning a full section with series when sectionId is supplied. It does not explicitly name sibling tools or explain how it differs from tools like get_indicator_series, 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?

It gives a clear usage pattern: call without sectionId to list sections, and with sectionId to retrieve detailed series. The schema reinforces that sectionId comes from the listing. It does not name alternatives or exclusions, but the conditional workflow is explicit.

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 read-only, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral information by specifying the shape of each returned item (last value, variation, period, favorable direction), which matters because there is no output schema. It says nothing about ordering, size, or caching, but the core disclosure is solid.

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, front-loaded with the verb 'Devolve', that packs the content list and the returned fields without a wasted clause. The colon construction keeps the enumeration readable.

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

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

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does: seven questions plus per-indicator last value, variation, period, and favorable direction. The remaining gap is relational — an agent still cannot tell from this text why it should pick get_pillars over get_panorama or get_bulletin.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter-level gap exists.

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 payload: returns seven questions about the Brazilian economy (growth, inflation, employment, public accounts), each paired with the indicators that answer them. The resource and content are unambiguous. It does not, however, distinguish itself from near-neighbours such as get_panorama or get_bulletin, which likely cover similar overview territory.

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: the description makes clear this is a fixed overview of the seven pillar questions, so an agent can infer 'use this for a high-level economic summary'. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling when a single indicator or a broader panorama is wanted.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful output semantics not present in any annotation: each component carries value, period, and the deterministic rule applied, and history is optional. It stops short of stating freshness or how the deterministic rules are chosen.

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 dense paragraph that front-loads the core deliverable (overall level) before the component breakdown and the optional history. Every clause carries information; it is only slightly dense to parse without structural markers.

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?

There is no output schema, so the burden of describing return structure falls on the description, and it discharges that well by enumerating levels, dimensions, and per-component fields. Only the lack of usage context relative to the many sibling read tools keeps it below a 5.

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 single parameter has 100% schema description coverage including range 0-365 and the default of 0. The description corroborates that daily level history is optional but adds no format or granularity detail beyond the schema. Baseline 3 is appropriate when the schema already documents the parameter fully.

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 resource (recession risk thermometer) and enumerates the exact output shape: overall level with three possible values, headline, and three dimensions (current state, momentum, forward pressure). This goes well beyond restating the title. It does not differentiate itself from siblings like get_panorama or get_indicator_latest, which is the only gap.

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 an agent should call this versus alternatives such as get_panorama, get_pillars, or get_indicator_latest. Usage is only implied by the noun 'thermometer'. No prerequisites, no exclusions, no routing guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to the extra context: timestamps are in UTC, the Focus Bulletin appears every Monday, and the no-argument default produces a today→+30d window. That is real behavioral information an agent cannot infer from the annotations, though return ordering or pagination is unmentioned.

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

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

Two sentences, no filler: the first describes content and format, the second the default window. Front-loaded with purpose and immediately followed by the most decision-relevant default.

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 two-optional-parameter read tool with full annotation coverage and no output schema, the description supplies content types, timezone, and default range — enough to call it correctly. Minor omissions (result ordering, whether the 120-day ceiling is enforced by the tool) keep it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by disclosing the default window behavior when 'from'/'to' are omitted, which the schema does not state. It does not, however, explain the 120-day cap interaction or formatting beyond what the schema already documents.

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 ('Lista') and resource ('divulgações oficiais agendadas'), then enumerates concrete examples (IPCA, PIB, PNAD, Copom) that make the returned content unmistakable. It is clearly distinct from siblings such as get_bulletin, list_bulletins, or get_indicator_series, which fetch bulletin content or series values rather than a forward-looking release schedule.

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 clear operating context by stating that omitting dates yields a window from today to 30 days ahead, which tells the agent how to call it in the common case. It does not explicitly name alternatives or exclusions (e.g., where to go for a specific indicator's value instead), so it stops short of a 5.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the natureza field can be Observado, Estimado, or Indisponivel, an Indisponivel card arrives without a value and must not be imputed, and the response includes upcoming official releases.

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, front-loaded with what is returned, then the natureza caveat, then upcoming releases. Each sentence carries useful information, though the indicator enumeration is slightly long.

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

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

With no output schema and no annotations about returns, the description does the heavy lifting by listing the returned indicators, the natureza field semantics, the Indisponivel rule, and upcoming releases. Only the exact response shape (field names/structure) is left unspecified.

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 schema documents both year (default = most recent with data) and territoryId (with examples and a pointer to list_territories). The description adds little parameter detail beyond implying the year scoping, 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?

States a specific verb and resource: returns the 10 key indicators for a territory in a given year, and enumerates them (PIB, população, inflação, etc.). The scope is clear enough to distinguish it from single-indicator siblings like get_indicator_latest, but it never names an alternative 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?

Implicitly indicates when to use it (a consolidated territorial profile rather than a series), and gives a data-handling rule (do not fill Indisponivel cards with estimates). However, it never states when to prefer a sibling such as get_panorama, get_indicator_series, or compare_indicators.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: results are sorted newest-to-oldest and each item carries a title, reference date and summary. Pagination limits are left to 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 with zero waste: the list scope and sort order come first, followed by the pointer to the detail tool. Every clause earns its place.

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

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

With no output schema, the description compensates by naming the returned fields, and pagination is fully specified in the schema. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, with both page and pageSize documented including defaults and the 1–20 range. The description adds no additional meaning about paging behavior, 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?

Names a specific verb and resource ("Lista as edições publicadas do Boletim Semanal") plus the ordering and the fields returned (título, data de referência, resumo). It is clearly distinguishable from get_bulletin, which serves the full text.

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

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

Explicitly routes the agent: "Use get_bulletin para o texto" states the alternative and the condition that selects it. It does not cover when-not to use this tool (e.g., searching vs. listing), but the primary sibling ambiguity is resolved.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the shape of each returned entry (categoria + indicadores relacionados), which partially compensates for the absent 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?

Two short sentences with zero waste: the resource and payload come first, the alternative second. Nothing redundant with 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?

For a one-parameter read-only list with no output schema, it says enough: what is listed, what fields come back, and where to go for detail. Pagination or ordering behavior is unstated but minor for a closed-world glossary.

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 'category' parameter is documented there as an exact-match optional filter. The description never mentions filtering at all, so it adds no meaning 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 and resource ('Lista os verbetes do glossário de conceitos econômicos') and specifies what each entry carries (category and related indicators). It also differentiates itself from the sibling get_concept, so an agent can choose between them without opening either schema.

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

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

Explicitly routes to get_concept 'para a definição', giving a clear alternative and the condition that selects it. It does not state exclusions the other way (e.g. when not to list), but the browsing-vs-lookup split is clear.

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, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds that the set is 'curado' (a fixed, curated catalog), which is mild reinforcement of the closed-world hint rather than new behavior. It says nothing about ordering or result volume.

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 tight sentences: the first defines the resource and its fields, the second gives use. Nothing is redundant and the definition is front-loaded.

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

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

With no output schema, the description carries the return-shape burden and does list the key returned fields (anos de início e fim, abrangência, resumo). That is sufficient for an agent to decide whether to call it; only ordering/volume details are absent, which is minor for a zero-param catalog.

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 no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is moot at zero params.

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 o catálogo curado de crises econômicas') plus scope ('brasileiras e globais'), so the agent knows exactly what comes back. It doesn't explicitly contrast itself with siblings, though none of the listed sibling names overlap this domain.

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?

'Útil para contextualizar quedas nas séries' gives a concrete use context that tells the agent when this catalog is relevant. No exclusions or explicit alternatives are offered, keeping it short of a 5.

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 destructiveHint=false, so the safety profile is covered. The description adds the non-obvious ordering behavior (newest to oldest) and the one-indicator scope, which the schema does not state. Pagination behavior is left to the schema rather than elaborated.

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

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

Three short sentences, front-loaded with the what and the ordering, then the filter advice, then the hand-off to get_daily_post. Nothing is redundant with 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?

For a read-only list tool with full schema coverage and no output schema, the description covers what is listed, the sort order, the filter and the follow-up call. It doesn't hint at the fields each item returns, which would help an agent decide whether to call this or go straight to get_daily_post.

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, pageSize and indicatorCode each documented including defaults and an example, so the baseline is 3. The description reinforces that indicatorCode is a filter over one indicator but adds no format or syntax detail beyond the schema's '"ipca"' example.

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 ('Lista') plus resource ('as pílulas publicadas, posts curtos e diários') with explicit scope ('sobre UM indicador') and ordering ('da mais recente para a mais antiga'). It also distinguishes itself from get_daily_post, which the agent can tell is the content-fetching sibling.

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

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

Explicitly says to filter by indicatorCode to see what the site has already written about an indicator, and routes the agent to get_daily_post for the actual text. That is a clear use case plus a named alternative, though it doesn't say when not to use this list.

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, openWorldHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by explaining the hasSeries and hasDetails flags and their downstream tool compatibility. It does not mention pagination, sorting, or result-size limits, so it is strong but not exhaustive.

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 tightly written sentences: the first defines the catalog contents, the second explains the two key flags and the intended starting point. It is front-loaded and every sentence provides actionable information with 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?

Given that this is a read-only catalog with full annotation coverage and no output schema, the description supplies the missing return-shape information by naming the entry fields and flag semantics. It also gives the workflow context needed to use the tool correctly as a discovery step.

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

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

The schema description coverage is 100%, documenting both query and category filters thoroughly, so the description does not need to repeat them. The description adds no extra parameter semantics beyond the schema, which meets the baseline for fully documented parameters.

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

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

States a specific verb and resource ('Lista os indicadores econômicos do Observatório BR') and enumerates exactly what each catalog entry contains (code, título, categoria, fonte, periodicidade, unidade). This makes it clearly distinguishable from siblings like get_indicator_details and get_indicator_series, which return richer or time-series data.

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

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

Explicitly positions the tool as the entry point ('Comece por aqui para descobrir os codes') and routes the agent onward: hasSeries=true points to get_indicator_series/compare_indicators, and hasDetails=true points to get_indicator_details. The agent does not have to infer when to use this catalog versus the data-fetching siblings.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful boundary that this tool lists articles rather than returning their full text, but it does not describe pagination, list fields, or other return behavior.

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

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

Two short sentences, front-loaded with the tool's purpose and followed by a clear pointer to the sibling tool for full text. There is no wasted wording.

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 listing tool with rich annotations, the description is nearly complete: it says what is listed and where to get the text. It could be slightly richer by describing what the list entries contain, but no output schema exists and the core selection need is covered.

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 for the description to compensate for. Baseline 4 is appropriate because the schema is empty and parameter meaning is not an issue.

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: it lists technical methodology articles explaining how the Observatory's indicators and models are calculated. It also distinguishes this listing tool from get_methodology, which is named for retrieving the text itself.

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

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

Gives a clear alternative by telling the agent to use get_methodology for the text, implying this tool is for discovering the available methodology articles. It does not spell out every when/when-not case, but for a zero-parameter list tool the routing guidance is clear.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the fixed cardinality (33 items), the composition of the set, and the metric fields returned, which lets the agent anticipate payload size and shape.

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

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

Two sentences, no waste: the first gives scope plus return fields, the second gives the follow-up action. The most actionable token (the id usage) closes the description cleanly.

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 carries the burden of describing the return shape, and it does so by naming all five fields and their units (R$ bilhões, milhões). For a zero-parameter, read-only listing, nothing an agent needs to call it correctly 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 takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no filtering inputs exist rather than suggesting options the schema does not have.

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: 'Lista os 33 territórios do Observatório' and immediately defines the exact scope (Brasil, 5 regiões, 27 UFs). It also enumerates the returned fields, so an agent knows precisely what it gets without opening a schema.

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

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

Explicitly routes the agent forward: 'Use o id em get_territory_profile', making this the discovery step before the profile lookup. It does not distinguish this from other list_* siblings (list_indicators, list_concepts, etc.), but the territory scope is unambiguous enough that confusion is unlikely.

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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds genuine value: accent-insensitive Portuguese matching, and the result-shape behavior that indicators appear only on page 1 while content is paginated.

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

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

Two sentences, no waste, with scope and the accent-insensitivity front-loaded before the result-shape note. 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?

With no output schema, the description responsibly explains the return shape (indicators vs paginated content). Only the relationship between page/pageSize and the indicators-only-on-page-1 rule could be spelled out more fully.

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

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

Schema coverage is 100%, so q, page and pageSize are fully documented in the schema; baseline 3 applies. The description adds only the page-1 constraint on indicators, which touches pagination but no other parameter meaning.

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

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

States a specific verb (busca) and enumerates the resources searched: boletins, pílulas, glossário de conceitos, artigos de metodologia, plus indicator panels matched by name. This clearly separates it from the list_* siblings, though it never names one 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 rather than stated: a text search across content types. It does not say when to prefer this over list_bulletins/list_concepts or get_concept, nor does it give exclusions. The note that panels appear only on page 1 is useful contextual guidance.

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