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

Annotations already cover read-only/idempotent/open-world, and the description adds real value: it names the external authority (INE), states what is returned, and reassures that no personal or salary data is transmitted externally. It stops short of discussing external-service failure modes or latency, which keeps it at 4.

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, all earning their place: capability, return values, then a privacy note. 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?

Covers inputs at a high level, enumerates all returned metrics in lieu of an output schema, and discloses the external dependency plus privacy posture. Only the month-format and error/timeout behavior for the external CPI call are 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 0%, so the description carries the burden: 'two CLP salaries in exact months' loosely maps to initial_salary/final_salary and start_month/end_month, and CLP is fixed. However the expected YYYY-MM month format and the currency parameter/default are never explained in prose.

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

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

States a specific verb+resource (compare two CLP salaries) with the method (official INE linked Chile CPI indices) and enumerates the outputs. It is plainly distinct from the payroll/employee siblings, so an agent can select it without opening the 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?

The use case (inflation-adjusted salary comparison between two exact months) is implied by the verb and the stated outputs, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as buk_salary_history for raw historical figures.

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 declare readOnly, idempotent, and closed-world, so safety is already covered; the description adds useful behavioral context by specifying the payload contents (permissions plus both schemas near schema). It does not mention latency, caching, or error behavior for unknown operationIds, which keeps it from a 5.

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, with the return contents front-loaded and the imperative guidance second. 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 does the work of explaining the return value (description, permissions, parameter schema, response schema), which is exactly what's needed. The remaining gap is the provenance of operationId, unaddressed in both schema and description.

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 0% and the single parameter is documented only as a bare string. The description implies operationId identifies "a Buk operation" but never says where to obtain it — most likely from buk_list_operations — which is the one detail an agent actually needs.

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 (return) and resource (official documentation for a Buk operation), enumerating exactly what comes back: description, permissions, parameter schema, response schema. An agent can distinguish it from buk_list_operations (which enumerates operations) by inference, though the sibling is never named explicitly.

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

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

"Always check this before using a new operation" gives a clear, actionable trigger condition tied to the agent's workflow. It stops short of naming alternatives or stating when the tool is unnecessary (e.g., for already-known operations), keeping it at a strong 4 rather than 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 openWorldHint=false, so safety is covered. The description adds real value beyond them by naming the searchable fields and explicitly limiting data scope ('Does not request HR data'), but it never mentions paging behavior or what the returned operation records contain.

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 purpose, then the searchable fields, then the follow-up step and scope limit. No repetition and nothing wasted.

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?

It is adequate for a discovery/catalog tool, but with no output schema the description should say what a listed operation looks like and that results are paginated (limit/offset exist with defaults). Those omissions are the main gaps for an agent deciding how many calls to make.

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 0%, so the description must carry parameter meaning; it clarifies what `search` and `tag` operate over (Spanish names, English paths, tags) and implies `method` filtering via 'operations'. However, `limit`, `offset` and the method enum are left entirely undocumented, so half the surface remains unexplained.

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 ('Discover every operation in the official Buk Chile API') and scopes the search dimensions (Spanish names, English paths, tags). It also separates itself from buk_describe_operation by saying you describe an operation afterwards, so an agent can pick between the two 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?

Gives an explicit workflow: search here first, then describe the exact operation before calling it, which implicitly routes to buk_describe_operation. 'Does not request HR data' sets a scope boundary against the HR/payroll siblings, though those alternatives are not named directly.

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, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond those annotations: parameters are validated against the official schema, results return original Buk data with pagination completeness, and permission errors are explicit.

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 three sentences and front-loads the core capability. The module examples are somewhat verbose but still reinforce scope, and the validation/return/error notes are useful rather than redundant.

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 generic open-world read tool with a fully described schema, the description covers validation, result behavior, pagination completeness, and permission errors. It is close to complete, though it could better explain how this tool relates to the operation-list and specialized read tools.

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

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

Schema description coverage is 100%, so the schema already documents operationId, path, query, and paginate. The description adds only the high-level note that parameters are validated against the official schema and does not contribute additional parameter-level semantics.

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: execute any documented GET operation against the authenticated Buk tenant. It clearly identifies the tool as a generic read-endpoint executor and lists covered domains, but it does not explicitly distinguish itself from the specialized read siblings such as buk_search_employees or buk_team_payroll.

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 the broad scope: any documented read endpoint can be called through this tool. However, the description does not explain when to prefer this generic tool over specialized siblings or when not to use it, so an agent must infer the routing.

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

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

Annotations already declare readOnly/idempotent/open-world, and the description still adds genuine context: that increase_percent is a simulation rather than a mutation, and that the computed figure deliberately excludes non-base employer costs. What is missing is any hint of the result shape beyond 'by currency' (per-currency lines? per-employee rows?) and what happens when no wages exist for the date.

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 packed sentences with no filler; the core computation is front-loaded and the scoping caveat trails it as a qualifier. 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?

For a tool with no output schema and 17% schema coverage, the description covers the calculation and its main interpretive trap (base wages vs total cost) but not the return structure or the three scope-controlling parameters. Adequate to call correctly in the simple case, thin for anything involving descendants or area resolution.

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 only 17%, so the description must carry the parameter burden and does not. It clarifies as_of ('explicit date') and increase_percent ('simulate a percentage change'), but leaves area_ids, company_id, include_descendants (default true, materially changes scope) and the team/area_ids/company_id selection relationship completely unexplained in either place.

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

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

The description gives a specific verb and resource set: sum a team's contractual base wages as of an explicit date, grouped by currency, plus a percentage-change simulation. The clause 'This is a base-wage run-rate, not total employer cost' sharply separates it from cost-of-employment interpretations, though it never names the obvious sibling buk_team_payroll, so the boundary with that tool must be inferred.

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: the 'not total employer cost' caveat tells the agent what answer this tool gives, so an agent can infer it should pick this for run-rate/base-wage questions. There is no explicit 'use X instead when...' routing, no prerequisite or permission guidance, and no indication of when to prefer buk_team_payroll or buk_salary_history.

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 and open-world behavior, so the bar is lower. The description adds a genuinely non-obvious behavioral trait: it will not infer or backfill missing salary history, so gaps mean no data rather than estimation. It does not describe output shape or error behavior for an unknown ficha.

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 with the core scope front-loaded and the limitation stated last; no filler. Minor cost is unexplained domain jargon ('ficha'), which an agent must infer means employee_id.

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?

A five-parameter read tool with no output schema and no parameter descriptions leaves real gaps: no return structure, no currency/units for wages, no month format, no default disclosure, and no statement of what happens when the ficha has no records. Adequate to call correctly, but not complete.

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

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

With 0% schema description coverage, the description must compensate, and it does reasonably: 'one exact ficha' maps to employee_id, the endpoint-month phrasing maps to start/end_month, CPI comparison maps to compare_cpi, and 'historical payroll' maps to include_payroll. It still omits the YYYY-MM format and the defaults (include_payroll=true, compare_cpi=false), which the schema supplies only structurally.

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

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

States a specific verb (Get) with a precisely scoped resource: contractual base-wage history, salary changes and historical payroll for one exact employee identified by ficha. It also names the optional CPI comparison axis, which distinguishes it from buk_team_payroll and buk_compare_salary_to_cpi.

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?

'for one exact ficha' implicitly excludes team/bulk lookups, but the description never explicitly says when to prefer buk_compare_salary_to_cpi or buk_team_payroll. The 'does not infer missing salary history' line is a useful exclusion, but only about data, not about sibling 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?

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds genuinely new behavioral facts: the response is a minimized directory and ambiguous lookups are flagged rather than resolved arbitrarily. It does not cover pagination/limit behavior, which keeps it from a 5.

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 dense sentences with the lookup keys front-loaded and the ambiguity contract stated last. Nothing is redundant and nothing could be cut without losing information.

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

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

For a read-only search with no output schema, the description adequately characterizes the return (a minimized directory, with multiple matches flagged). The remaining gap is the unspecified status filter and default/maximum result count.

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 0%, so the description carries the burden. It usefully explains what the 'query' parameter accepts (name, email, ficha ID or document), but says nothing about 'limit' or the activo/inactivo/pendiente 'status' filter, leaving two of three parameters undocumented.

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 plus resource (find Buk employees) and enumerates the four lookup keys (name, email, ficha ID, document). The sibling tools are all in unrelated domains (payroll, operations, salary), so there is no real ambiguity to disambiguate from.

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 search keys imply when to reach for this tool (resolving a person from any identifier), and 'never guesses which person is intended' hints at the multi-match workflow. However, it never states when not to use it or names an alternative for enumerating employees, so usage is only implied.

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 safety (readOnly, idempotent, openWorld), and the description adds real behavioral context: how the standard employer cost is derived (reconciled earning/contribution/family-allowance lines), that custom Finance-approved expense accounts are honored, and that missing data are surfaced explicitly rather than silently dropped. It stops short of describing output shape or the cost of a wide open-world lookup.

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, front-loaded with the core capability and its data basis, with no filler. Slightly dense in the second sentence (reconciled earning/contribution/family-allowance lines) but every clause carries 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 12-parameter aggregation tool with no output schema, the definition covers the calculation model and default scope but is silent on the team-vs-area_ids/company_id resolution path (documented only in the schema), currency handling, and what the returned breakdown looks like. Adequate, but an agent would still guess on several inputs.

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 only 33%, so the description needs to compensate. It does explain include_open (closed-only default), compare_previous (prior-month change), expense_accounts (Finance-approved, standard-cost derivation) and family-allowance handling, but leaves area_ids, company_id, cost_centers, payroll_currency, include_accounting and include_descendants entirely unaddressed.

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 opening sentence names a specific verb (calculate) and resource (team monthly gross/net payroll, employee breakdown, prior-month change) plus the data source (historical jobs). It is clearly distinct from buk_salary_history or buk_recurring_payroll, though it never names those siblings explicitly.

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

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

The description states a default scope ('Only closed payroll is included by default') but gives no when-to-use / when-not-to-use guidance and never points to buk_salary_history, buk_recurring_payroll or buk_compare_salary_to_cpi as alternatives. An agent must infer selection criteria from the sibling names alone.

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