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

Beyond the destructiveHint annotation, the description discloses important behavioral traits: cancellation cannot be undone, HiBob refuses filled positions, and the tool is rate-limited to 10 requests/minute. It also describes the return contract (JSON confirmation or an 'Error:' string). No contradiction with annotations is present.

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 front-loaded with the core purpose and key warning, then follows a compact structured format for Args, Returns, and Rate limit. Every sentence adds value: purpose, precondition, irreversibility, parameter, return behavior, and rate limit. No filler or redundancy.

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

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

For a single-parameter, clearly scoped cancellation tool, the description covers the essential context: purpose, precondition, irreversibility, error return, and rate limit. An output schema exists, so detailed return documentation is not required. Nothing material is missing for an agent to invoke 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%, and the only parameter, position_id, is already documented in the schema as 'ID of the position to cancel.' The description's Args section merely repeats this meaning without adding format, source, or validation details, so it stays at the baseline.

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 starts with a specific verb and resource: 'Cancel a planned position, removing it from the workforce plan.' It clearly names the action and the object, and the mention of 'planned position' differentiates it from active/filled position operations and from sibling tools like create/update position.

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 explicitly tells the agent when to call this tool (to cancel a planned position) and gives a concrete precondition: check '/position/status' with hibob_search_positions first because HiBob refuses to cancel filled positions. This is actionable usage guidance that also names the sibling tool to use beforehand.

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?

Beyond the annotations, the description discloses important runtime behavior: rate limiting ('HiBob allows only ten write calls per minute'), pre-request validation of required fields, and the fact that exactly one position is created per call. It also describes the return format and error convention, which is valuable context for an agent handling failures.

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 well-structured with a clear opening definition, explicit prerequisites, parameter summaries, return format, examples, and an anti-example. Every sentence earns its place, and the most important usage guidance is front-loaded. Despite length, it remains scannable and useful.

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 three nested object parameters and an open-world schema, the description is complete: it explains what a position is, what counts as the opening, how to resolve list IDs, what constraints apply, what the response looks like, and how to avoid misuse. The presence of an output schema reduces the burden of explaining return values, and the description still covers them.

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 input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds value by clarifying that all three arguments are flat mappings, by explaining that HiBob list values must be list item IDs, and by instructing the agent to resolve those IDs first. This goes beyond the schema's individual field 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?

The description states a specific verb and resource: 'Create a planned position, with its opening and optional budget.' It clearly distinguishes this from sibling tools, especially hibob_create_position_opening, by explaining that a position is a budgeted seat and must be created with its first opening. The 'one position per call' constraint further sharpens the purpose.

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 explicitly tells the agent when to use this tool and when not to, naming the alternative: 'Don't use when: adding a second vacancy to an existing position (use hibob_create_position_opening).' It also gives a concrete example of when to use the tool and instructs the agent to resolve list IDs with hibob_get_company_named_lists and hibob_list_workforce_fields before calling.

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 indicate this is a mutating, non-idempotent operation. The description adds useful behavior beyond that by documenting the exact return format (JSON with positionBudgetId), error message prefix ('Error:'), and the 10 requests/minute rate limit. It does not cover duplicate-creation consequences, but the idempotentHint=false annotation covers that signal.

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 well-structured with Args, Returns, Examples, and Rate limit sections, and the main purpose is front-loaded in the first sentence. It is slightly verbose due to some duplication with the schema, but all included details earn their 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 mutating tool with two required parameters and an output schema, the description covers success/error output, rate limiting, and a practical example. The main missing context is explicit guidance about updating existing budgets versus creating new ones, though sibling names partly compensate.

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 already has 100% coverage, documenting position_id and fields with required and optional field IDs. The description adds value with a concrete natural-language example mapping 'Budget 65k a year' to expectedBaseSalaryCurrencyValue, salaryPayPeriod, and currency, plus clarifying that fields is a flat mapping.

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 'Attach a salary and cost budget to a position,' which clearly identifies the action and resource. This differentiates the tool from siblings like hibob_update_position_budget and hibob_search_position_budgets by implying a create operation on a position budget.

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

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

The description provides a concrete example ('Budget 65k a year for that role') that helps an agent recognize when the tool is appropriate. However, it does not explicitly state when to use this instead of hibob_update_position_budget or mention any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds meaningful behavior beyond those: a rate limit of 10 requests/minute, the exact return JSON shape, and an error prefix. This helps an agent anticipate failures and throttling.

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 well-structured: a one-sentence purpose, labeled Args, Returns, and Rate limit. Every line adds useful information without fluff or repetition.

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?

The description covers return format, error behavior, and rate limiting, while the output schema handles the return structure. It doesn't mention prerequisites beyond 'existing position' or auth concerns, but with a 2-parameter tool and rich schema, it is nearly complete.

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

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

Schema description coverage is 100%, and the schema already documents the required expectedStartDate and optional fields. The description restates parameter names and short meanings, adding little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with 'Add a vacancy to an existing position,' naming a specific action and resource. It clearly distinguishes this from sibling tools like create_position or update_position_opening, and the phrase 'existing position' signals the parent context.

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

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

The description implies this tool is for adding a vacancy to an existing position, which gives some usage context but does not explicitly say when to prefer it over create_position or update_position_opening. No alternatives or exclusions are mentioned.

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

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

Beyond the annotations already marking this as destructive and non-read-only, the description adds critical behavior: the action is permanent and cannot be undone through the API, the rate limit is 10 requests/minute, and the return value is either a JSON confirmation or an 'Error:' prefixed message. This substantially exceeds what annotations alone convey.

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 well-structured and front-loaded with the primary purpose, followed by irreversible consequences, confirmation guidance, args, return value, and rate limit. The Args block is slightly redundant with the 100%-covered schema, but the overall length is reasonable and every section serves a clear purpose.

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 destructive two-parameter operation, the description is complete: it explains irreversibility, provides a verification step, specifies the return format including failure behavior, and notes the rate limit. Despite the presence of an output schema, the return description adds further clarity.

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 both parameters are already fully documented in the input schema. The description's Args section largely repeats this information without adding new semantics, though it does clarify the relationship between position_id and opening_id.

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 'Permanently remove an opening from a position,' which clearly identifies the specific verb (remove), resource (opening), and container (position). This distinguishes it from sibling tools like create, update, and search operations on openings and positions without needing to inspect schemas.

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 explicitly instructs the agent to 'Confirm the opening ID with hibob_search_position_openings before calling,' naming the exact sibling tool to use first. It also communicates that the deletion is permanent, making the 'when to use' decision unambiguous.

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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral details: list_name is optional and None returns all lists, and the return value is a JSON mapping to IDs and display names. No contradiction with annotations.

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 well-organized into Args, Returns, and Examples. Every sentence advances understanding, and the most important workflow context ('position fields must use named lists') 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?

For a single-optional-parameter read-only lookup, the description provides purpose, usage timing, parameter behavior, return shape, and an example. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema fully documents list_name. The description adds value with concrete examples ('Which departments exist?' -> list_name='department') and by restating the None/omit semantics in plain language, going slightly beyond the schema baseline.

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 and resource: 'Look up the allowed values of HiBob's named lists.' It further clarifies that the tool resolves names to IDs used by hibob_create_position and hibob_update_position, making its distinct role among position-related siblings clear.

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 explicit context: position fields must come from named lists, and this tool should be used before creating or updating positions to convert names to list-item IDs. It does not mention when-not-to-use or contrast with an alternative lookup sibling, but none is apparent among the listed 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by stating the return format, that it returns field IDs/types/required flags, and the rate limit of 50 requests/minute.

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 well-structured and front-loaded with the core purpose. It uses compact sections for args, returns, examples, exclusions, and rate limit without redundant filler.

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

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

For a simple list tool with one parameter, rich schema coverage, a full output schema, and comprehensive annotations, the description covers everything needed: when to call it, what it returns, and when to use an alternative.

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 input schema already fully documents the single parameter with an enum and description, so the baseline is 3. The description adds extra value by giving natural-language examples mapping user intents to specific object_type values.

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 it lists available fields on a HiBob workforce planning object. It also distinguishes itself from sibling tools by explaining it returns the field IDs that every other tool expects, making its purpose and scope unambiguous.

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

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

The description explicitly says to call this before searching or creating anything. It also provides a concrete exclusion: don't use it for allowed list values, and names the sibling tool to use instead.

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 safe/read-only nature is established. The description adds useful behavioral context beyond annotations by stating the rate limit ('100 requests/minute') and the pagination contract via 'has_more' and 'next_cursor'.

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 well-structured and front-loaded with purpose and use case, followed by compact Args, Returns, and Rate limit sections. It is slightly redundant with the schema's parameter descriptions, but overall every section earns its place and there is no fluff.

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?

The description covers the essential operational details: what the tool returns, pagination fields, parameter constraints, rate limits, and a representative use case. Given that an output schema is present and annotations cover safety, nothing critical is missing for an agent to call this tool 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%, so the schema already documents all parameters. The description mostly restates the schema, adding only minor practical details like 'None to start' for cursor and 'display labels' for include_human_readable, which does not significantly exceed the schema baseline.

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 'Search position budgets' and specifies 'planned salary and total cost per position,' making the tool's subject and scope immediately clear. It is clearly distinguishable from sibling search tools like hibob_search_positions and hibob_search_position_openings because it focuses on budget/cost 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?

The description explicitly says 'Use this for cost roll-ups across planned headcount' and gives a concrete example, which tells the agent when to select this tool. It does not explicitly name alternatives or state when not to use it, but the use-case guidance is specific enough to route correctly.

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 mark the call as read-only and idempotent, and the description adds valuable behavioral details beyond them: pagination through has_more/next_cursor, the exact JSON return envelope, the instruction to call again with next_cursor, and a concrete rate limit of 100 requests/minute. Nothing in the description contradicts the annotations.

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 well-structured with purpose, args, returns, example, and rate limit. It is front-loaded and readable, though the Args section largely duplicates the input schema and could have been trimmed. The example and pagination details justify the overall length.

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 paginated search tool, the description covers the full call lifecycle: required fields, optional filters, pagination loop, return envelope, rate limit, and a concrete usage example. The output schema covers return values and annotations cover safety, so no critical information is missing for correct invocation.

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; the description mostly restates parameter meanings but adds a worked filter example showing exactly how to encode field_id, operator, and values. It also clarifies the status domain (vacant, starting, filled, departing), which helps agents build correct filters without opening 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 'Search position openings' and immediately defines them as 'the vacancies attached to positions,' which clearly identifies the resource and separates the tool from position-level searches. It also explains that openings carry the recruitment view, making the tool's domain concrete.

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

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

The description provides clear context for when this tool is relevant: it exposes recruitment status, expected start date, and whether a seat is vacant/starting/filled/departing. It also includes a natural-language example ('Which openings are still vacant?') with the matching filter. However, it does not explicitly name alternatives or state when not to use this tool versus sibling search 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses no pagination, rate limit of 100 requests/minute, and the response shape with values/display, including that values carry IDs needed by update tools. This gives agents actionable expectations for invocation.

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?

Well-sectioned with opening, return format, warning, args, returns, example, and rate limit. The Args section somewhat duplicates schema, but the overall structure is clear and front-loaded with key behavioral caveat (no pagination) early.

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 rich annotations, complete schema, and the description's own return-shape and example, an agent can correctly invoke it, including constructing valid filters. It even covers rate limiting and differentiates from the closest sibling. 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 description coverage is 100%, so the schema already documents fields, filters, and include_human_readable. The description adds a concrete filter example ('Which positions are vacant?') and notes filters are combined by HiBob, a slight semantic addition, but largely restates parameter meaning. 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 clear verb+resource: 'Search the company's positions.' It distinguishes from siblings by specifying one entry per matching position and explicitly contrasts with hibob_search_position_openings. No ambiguity about what resource is queried.

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 'Don't use when: you need opening-level detail... (use hibob_search_position_openings),' naming the alternative and the condition. It also advises requesting only needed fields and filtering in large organizations due to no pagination, which is practical usage context.

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 establish readOnly=false, idempotent=true, and destructive=false. The description adds relevant behavior beyond annotations: only supplied fields are modified, the response is a JSON string or error, and there is a 10 requests/minute rate limit. No contradiction with annotations 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?

The description is compact and well-structured: purpose, partial-update semantics, prerequisite lookup tool, args, return format, example, and rate limit all appear in a tight, readable layout. Every section earns its place with no redundant filler.

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

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

For a two-parameter tool with rich schema coverage, annotations, an output schema, and a clear example, the description provides all essential call-time information. An agent can correctly select the tool, find the required position ID, format the update payload, 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds value with the example mapping '/position/effectiveDate' and clarifies that fields is a flat mapping from field IDs to new values, helping agents construct valid payloads beyond the schema's field list.

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 'Change details of an existing position,' naming a specific verb and resource, and is reinforced by the title 'Update a HiBob position.' This makes it clearly distinct from sibling tools like create, cancel, or opening/budget updates.

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 explicitly instructs agents to use hibob_search_positions first to find the position ID, which is a concrete precondition. It does not enumerate when to avoid this tool versus update_position_opening or update_position_budget, but the 'existing position' scope together with sibling names provides adequate context.

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 indicate the operation is not read-only, is idempotent, and is not destructive. The description adds useful behavioral context beyond annotations by specifying the return format (JSON confirmation or error message prefixed with 'Error:') and the rate limit of 10 requests/minute.

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 well structured and front-loaded: a one-line action, lookup guidance, parameter explanations, return behavior, and rate limit. Every section earns its place with no filler or repetition of the annotations.

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 3-parameter update tool with an output schema, the description is nearly complete: it explains how to find the budget ID, what the fields parameter means, what the response looks like, and the rate limit. It could further clarify whether unspecified fields are left unchanged, but this is largely inferable from 'fields to change.'

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 already covers all three parameters with descriptions, so the baseline is 3. The description adds meaningful semantics by explaining that 'fields' is a 'flat mapping of field IDs to new values' and that 'position_id' is the parent position ID, reinforcing the relationship between the required 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?

The description opens with 'Change an existing position budget,' a specific verb+resource phrase that precisely identifies the tool's function. It also points to hibob_search_position_budgets for finding the budget ID, which implicitly distinguishes this update operation from the search and create siblings.

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

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

The description gives a clear usage step: use hibob_search_position_budgets to find the budget ID before calling this tool. It does not explicitly list exclusions or alternatives beyond that prereq, but the 'existing position budget' wording and sibling names make the intended usage unambiguous.

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?

Beyond the annotations, the description discloses the return format ('JSON confirming the update, or an error message beginning with Error:') and the rate limit (10 requests/minute). It does not expand on side effects or permission needs, but the annotations already convey read/write and destructiveness signals.

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 with the core purpose, then follows a clear Args/Returns structure. The Args block is somewhat redundant with the schema, but overall it is efficient and 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?

Combined with the rich input schema, output schema signal, and annotations, the description covers the key invocation details: parameters, return behavior, and rate limiting. It does not exhaustively list all updatable fields, but the examples plus open fields schema make the tool usable.

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 largely restates the parameter names and adds no significant meaning beyond the schema, though the schema's 'fields' example already provides formatting guidance.

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 action—'Change an existing opening'—and gives concrete examples of what can change ('expected start date or recruitment status'). This clearly distinguishes it from create, cancel, delete, and budget-related siblings.

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

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

The phrase 'existing opening' implies the tool is for updating already-created openings, and the sibling names clarify lifecycle alternatives. However, the description does not explicitly state when to choose this over create_position_opening or delete_position_opening, nor does it mention any preconditions.

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