QuailOS

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: completing a task also mutates recurrence, which is a side effect an agent would not predict from the annotations or schema alone.

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 core action and zero padding. The second sentence is a little vague ('supports confirm and idempotency validation') but costs almost nothing.

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

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

No output schema exists, and the annotations carry the destructive safety profile, so the description need not explain return values. It still leaves the key mutation semantics unexplained: what 'update recurrence' actually does (spawn the next occurrence? alter the schedule?) and what completing does to the task record.

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 all six parameters including confirm, idempotencyKey, and hoursLogged are documented in the schema. The description adds no syntax or semantic detail beyond restating that confirm and idempotency are supported, 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 ('Mark a task as Completed') and discloses a side effect ('update recurrence'), so the agent knows this is a state transition rather than a creation or deletion. However it never names or distinguishes itself from the sibling task tools (create_task, delete_task, get_tasks), leaving that 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?

There is no statement of when to use this versus delete_task or get_tasks, nor any prerequisites beyond the schema's confirm flag. The clause about confirm/idempotency is a capability note, not usage 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 declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds that a confirm-dry-run flow and idempotency validation exist, which is mildly useful context beyond the annotations, but it does not explain what a dry-run returns, what happens on failure, or why idempotentHint is false while an idempotencyKey is accepted.

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 no filler, and the core action is front-loaded in the first clause. Every sentence carries information an agent can use.

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 should say more about what creation returns and how the dry-run preview differs from a committed event, which it does not. Annotations and a fully documented schema cover the basics, so it is adequate but leaves meaningful gaps for a mutation tool.

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 every parameter including confirm and idempotencyKey is already documented in the schema. The description only echoes the existence of confirm and idempotency handling without adding format, constraint, or default detail beyond what the schema provides, 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 ("Create a new calendar event") and scopes it to the farm's timeline, which is enough to separate it from get_calendar_events and delete_calendar_event. It stops short of naming those siblings explicitly, so the differentiation is implied by the verb rather than stated.

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

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

The description gives no when-to-use, when-not-to-use, or alternative guidance. "Supports confirm and idempotency validation" only hints at the commit/dry-run mode, and even that condition is fully explained by the confirm parameter in the schema, not by the 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the write-safety profile is covered. The description adds the deduping behavior, but it never says what happens on a dedupe hit (error, merge, skip) or what confirm=false actually returns, and "supports idempotency validation" sits in tension with idempotentHint=false without explaining that the key is what makes retries safe.

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 no filler, and the core action is front-loaded ahead of the capability note. Nothing can be trimmed 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 9-parameter mutation tool with no output schema, the description covers the action and two key behaviors but omits the dedupe outcome, error conditions, and required auth context. Annotations carry the safety profile, so this is adequate but leaves real gaps an agent would hit at call time.

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 all nine parameters are already documented, including the deduping notes on email/phone and the dry-run semantics of confirm. The description only restates those same two concepts and adds no format, default, or constraint detail beyond the schema; 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 names a specific verb and resource ("Add a new customer to the CRM") and adds a distinguishing qualifier ("with deduping"). It separates the tool from read-oriented siblings like get_customer_details, though it never names a sibling explicitly, 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?

"Supports confirm and idempotency validation" implies a preview-then-commit workflow, which is useful implied usage. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as get_customer_details for checking existing customers before creating one.

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, so safety is partly covered. Beyond that the description discloses two useful behaviors: duplicate/matching submissions are handled as upvotes rather than new records, and confirmation is mandatory before the write. It does not explain the confirm=dry-run flag or what a duplicate does to the caller.

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, and the core purpose is front-loaded ahead of the imperative guardrail. Every sentence carries distinct information; nothing could be cut without losing meaning.

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 mutation tool with no output schema and annotations that cover the write/idempotency profile, this is close to sufficient: the agent knows what it does, the confirmation requirement, and the dedup path. Minor gaps remain around exactly how 'matching' is determined and how farmId scopes requests.

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 farmId, title, description, area, confirm, and idempotencyKey. The description adds no parameter-level detail (e.g., that 'confirm' implements the confirmation requirement) and only implicitly gestures at the confirm flag. 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?

The description uses specific verbs and a specific resource: 'Submit a new feature request or upvote an existing matching request.' An agent immediately knows this is a write into the feature-request backlog. It does not name the read counterpart (get_feature_requests) or otherwise differentiate itself from siblings, 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 defines the two entry conditions ('new request' vs 'existing matching request'), which is real routing logic, and adds an operational rule ('ALWAYS ask for confirmation before writing'). It never names an alternative tool or an explicit when-not-to-use case, so it stops short of 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=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral requirement (mandatory confirmation before writing), but says nothing about the dry-run/confirm semantics or idempotency behavior the schema implies. Adds some value over annotations but not rich context.

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

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

Two short sentences with zero waste; the core action is front-loaded and the safety requirement follows immediately. Nothing to trim.

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

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

For an 8-parameter mutation tool with no output schema, the description is thin: it never indicates what a successful call returns (e.g. the created hive ID) or how dry-run mode responds. The confirmation sentence covers the most important risk, but return/response expectations and idempotency handling are left to inference.

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 all 8 parameters are documented in the schema, including the enum on 'source' and the dry-run meaning of 'confirm'. The description contributes no additional parameter meaning, which is acceptable at full coverage but earns only 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?

States a specific verb+resource: 'Register a new beehive in an apiary yard.' This clearly distinguishes it from read siblings like get_beekeeping_apiary and from adjacent log_* tools such as log_hive_inspection. It stops short of naming the alternative tools an agent might confuse it with.

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 only guidance is procedural ('ALWAYS ask for confirmation before writing'), which is a precondition rather than selection guidance. Nothing says when this tool is preferred over siblings or under what circumstances a hive should be registered rather than inspected or logged. An agent gets no routing help.

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, idempotentHint=false, and openWorldHint=false, so safety is largely covered. The description adds a genuinely useful confirmation requirement, but says nothing about the dry-run/confirm semantics, idempotency behavior, or that a ticket ID is returned.

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 action and ending with the operational constraint; no filler. It is perhaps leaner than ideal for an 8-parameter mutation tool, but nothing is 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?

For a write tool with 5 required parameters and no output schema, the description omits what a successful call returns, how the dry-run/confirm flow behaves, and how idempotencyKey interacts with the idempotentHint=false annotation. Annotations and the 100%-covered schema fill most gaps, so the omission is real but not severe.

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% across all 8 parameters, including the confirm dry-run flag, idempotencyKey, and relatedRecordId, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond it, which is the baseline expectation at full coverage.

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 ("Create a new support ticket"), which is enough for an agent to identify the action. However, it offers no differentiation from nearby siblings such as create_feature_request or reply_to_ticket, which share the support/ticketing 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?

The only guidance is "ALWAYS ask for confirmation before writing," which is a behavioral rule, not a when-to-use cue. Nothing says when a ticket should be filed versus a feature request, or how this relates to reply_to_ticket for existing tickets.

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 and destructiveHint=false, so safety is covered. The description adds the useful, non-annotated fact that the tool supports a confirm/dry-run preview and idempotency validation, but says nothing about the permission requirements, what the created task returns, or what happens on duplicate submissions. Note the mild tension with idempotentHint=false, which the client-supplied idempotencyKey only conditionally overrides.

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 the action front-loaded and no filler. It is efficient, though its brevity contributes to the missing context noted elsewhere rather than being a model of dense concision.

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 eight parameters, no output schema, and annotations that only cover the safety profile, the description does the minimum: it names the resource and two behavioral flags. It omits prerequisites (e.g. that farmId must reference an existing farm) and what a successful creation yields, leaving the agent to infer those.

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 regardless. The description merely echoes the confirm and idempotencyKey parameters already documented in the schema and adds no syntax, defaults, or interaction details beyond them.

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 ('Create a new farm management task'), which is enough to tell it apart from sibling creation tools like create_hive or create_calendar_event by resource. It stops short of naming any sibling or scope constraint 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?

'Supports confirm and idempotency validation' hints at a dry-run workflow but gives no when-to-use guidance, no prerequisites, and no routing to alternatives. Nothing tells the agent when this tool is the right choice over the many other create_* 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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds value by stressing permanence ('Permanently delete') and mandating user confirmation, which is behavior the annotations do not express.

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 filler; the action and its permanence come first, and the safety directive follows. 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 destructive delete with full annotation coverage and full schema coverage, nothing material is missing. The confirmation requirement and permanence warning make the description sufficient 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 farmId, eventId, and confirm are all documented in the schema itself. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema carries full coverage.

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 ('delete a calendar event') and constrains the scope to 'this farm'. It is trivially distinguishable from siblings like create_calendar_event and get_calendar_events without opening any 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?

It gives an explicit imperative precondition ('ALWAYS ask the user to confirm first'), which is strong usage guidance for a destructive tool. It does not name an alternative tool or spell out when-not-to-use, but the sibling create/get tools make the intent 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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description reinforces irreversibility ('Permanently') and adds a mandatory user-confirmation step, which is genuinely new behavioral guidance beyond the structured fields. It does not say whether related records (time logs, etc.) are also removed.

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, zero filler, with the destructive scope stated first and the confirmation requirement immediately after. Nothing to trim.

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

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

For a simple three-required-parameter delete with full schema coverage and no output schema, the description covers action, scope, and the confirmation safeguard. The only real gap is the effect on dependent data and any error behavior, which are not mentioned.

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 IDs and the confirm flag are already documented in the schema, establishing the baseline of 3. The phrase 'in this farm' loosely ties to farmId but adds no format, constraint, or example beyond the schema text.

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 ('Permanently delete a task') and scopes it ('in this farm'), so an agent knows exactly what is removed. It does not name or contrast with any sibling (e.g., complete_task, delete_calendar_event), leaving differentiation 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?

The instruction to ask the user for confirmation first is a concrete, actionable usage rule, but it addresses workflow rather than when-to-use versus alternatives. No conditions for choosing deletion over completing or archiving a task are given.

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 usefully adds that the output is a set of sire/dam pairings rather than a single answer, but it says nothing about ordering, ranking, or what happens when no pairing is viable.

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

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

A single sentence that front-loads the lookup type and then states the target and output shape; no wasted clauses. The 'Perform a reverse genetic lookup to' preamble is slightly ceremonious but does not obscure 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?

With no output schema, the description carries responsibility for explaining returns; it does state that pairings (sire and dam) are returned, which is the key fact. It omits result ordering, behavior when no pairings exist, and how limit truncates the set, leaving a few gaps for a lookup tool.

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 only two parameters, so the schema already documents target_variety (name or ID, case-insensitive) and limit (default 10). The description adds no format, matching, or truncation detail beyond what the schema provides, making the baseline 3 correct.

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 (find) and resource (all possible parent pairings, sire and dam) plus the goal (producing a targeted plumage variety), which is far more informative than the tool name alone. It does not explicitly distinguish itself from the sibling predict_quail_cross, which appears to be the inverse operation, so it stops 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?

The 'reverse genetic lookup' framing implies the scenario (working backward from a desired offspring variety to candidate parents), which is adequate implied usage. However, it names no alternative and gives no when-not guidance, so an agent must infer that predict_quail_cross is the forward-direction sibling rather than being told.

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 the authorization requirement, which is useful context, but it does not address pagination, result size, or scope limits.

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

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

Two short sentences, with the action and returned resources front-loaded before the authorization note. No filler, though the trailing apiKey clause is slightly confusing rather than earning 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 usefully enumerates the returned entities (yards, hives, queen statuses, varroa inspections), which is exactly what an agent needs to judge relevance. The only gap is the unexplained apiKey authorization requirement that has no corresponding parameter.

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?

Single parameter with 100% schema description coverage, so the schema already documents farmId fully; baseline 3 applies. The description restates that farmId is required but adds no format or constraint detail, and its mention of an 'apiKey' is not represented in the schema at all.

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 concrete verb (Retrieve) and enumerates the resources returned: yards, hives, queen statuses, varroa inspections. This separates it from generic siblings like get_bird_batches or get_egg_collections, though it does not explicitly name which sibling to prefer.

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

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

There is no when-to-use guidance, no prerequisites beyond an authorization mention, and no routing to related tools such as log_hive_inspection or update_queen_status. The agent must infer the context entirely.

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 fully covered. The description adds one genuinely useful behavioral fact beyond that: the result set spans both active and archived batches. It says nothing about pagination behavior or ordering, which the schema only partially implies.

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 verb first and no filler. Every word 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 simple read-only list tool with full schema coverage and annotations carrying the safety profile, the description is nearly sufficient. Minor gaps remain around pagination semantics, but no output schema is needed to explain return values.

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 farmId, limit and cursor are all documented in the schema itself. The description adds no additional semantics (e.g. whether farmId scopes the query or whether cursor is opaque), 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 gives a specific verb ('Retrieve') and resource ('poultry census batches from the flock inventory'), which cleanly separates it from the write sibling log_bird_batch. It does not explicitly name or contrast with any sibling, 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?

There is no guidance on when to call this versus alternatives (e.g. log_bird_batch for writes, or per-farm filtered lookups). The phrase 'active and archived' hints at scope but does not state a use condition or exclusion.

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 readOnly, idempotent, non-destructive, closed-world, so the bar is low. The description still adds genuine context beyond them: the set of event categories returned and the apiKey authorization requirement, which annotations do not express. It omits default time-window behavior, but that is minor given the annotation coverage.

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 resource and content scope front-loaded and the prerequisite trailing. No filler 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?

For a read-only list tool with full schema coverage, rich annotations, and no output schema, the definition covers purpose, returned content, and auth. The only gap is unspecified default date-range behavior when startDate/endDate are omitted.

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 all three parameters (farmId, startDate, endDate) are already documented with types and format hints. The description only restates that farmId is required and adds nothing about the date filter syntax, so baseline 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('calendar events') and enumerates the event types covered (hatches, local events, rentals, task due dates), which distinguishes it from get_tasks and get_hatches. It does not explicitly route to create_calendar_event/delete_calendar_event, but the read/write split is obvious from the names.

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 content-type list and the farmId/apiKey prerequisite, but there is no explicit when-to-use versus alternatives (e.g., get_tasks for pure task lists) and no exclusions. Adequate but leaves routing to inference.

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 an authorization requirement (farmId and apiKey), which is useful context beyond the annotations, but it says nothing about pagination or return scope despite cursor/limit params.

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 action front-loaded and no filler. Efficient, though the auth sentence could be integrated more naturally.

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 lookup tool whose annotations cover safety and whose schema fully documents parameters, the description is nearly complete. It could hint at what the 'detailed profile' returns, but with no output schema that is a minor 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?

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no syntax or constraints beyond what the schema provides for emailOrName, limit, or cursor, 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 (Retrieve) and resource (detailed profile of a specific customer) with the lookup key (email or name). It clearly distinguishes a read operation from the sibling create_customer, though it does not name that sibling 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?

Offers no when-to-use or when-not-to-use guidance and no routing to alternatives such as create_customer. The only contextual hint is 'by email or name,' which is really parameter detail rather than usage 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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered elsewhere. The description adds a useful auth requirement (apiKey authorization), but says nothing about pagination behavior or result shape beyond what the schema already encodes.

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, zero filler, with the core action front-loaded and the constraint second. Nothing needs trimming.

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 some burden for describing returns; it does name 'logs and collection counts' but gives no shape, ordering, or pagination expectations. Annotations and full parameter coverage compensate for much of the rest, leaving it adequate but thin.

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 fully documents limit, cursor, farmId, startDate and endDate including timezone semantics. The description only restates the farmId requirement, adding no meaning beyond the structured fields; 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 ('Retrieve daily egg production logs and collection counts'), which is clearly distinct from the write sibling log_eggs. It does not explicitly name or contrast with any sibling, so it stops 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?

There is no guidance on when to use this tool versus alternatives (e.g., log_eggs for writing, or date-range scoping decisions). The only condition stated is a permission prerequisite ('Requires farmId and apiKey'), which is not usage 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the authorization requirement (apiKey), which is genuinely beyond the annotations, but says nothing about pagination behavior despite limit/cursor parameters existing.

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 the core purpose front-loaded and no filler. The second sentence slightly restates the schema's required farmId, but the auth note 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 read-only listing tool with a fully documented schema and no output schema, the description is nearly sufficient — an agent knows what it lists, whose data it returns, and what auth it needs. Only return-shape/pagination expectations are left implicit.

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 every parameter is already documented in the schema (limit, cursor, farmId, status, startDate, endDate). The description adds no filtering syntax, date-format, or status-value detail beyond what the schema states, 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 ('List') and resource ('feature requests') with a scope qualifier ('submitted by this farm'). It is distinguishable from the sibling create_feature_request, though it never explicitly names that sibling as the write counterpart.

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 sentence 'Requires farmId and apiKey authorization' gives a prerequisite, which is useful, but there is no guidance on when to prefer this over alternatives or on what the returned list is scoped to beyond the farm. Usage is implied by the tool name rather than explained.

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 one piece of behavioral context beyond that—the apiKey authorization requirement—but says nothing about return shape, pagination, or scope limits, so it earns a modest 3.

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 the primary purpose front-loaded and no filler. The bundling of three distinct resources in one clause is slightly dense 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 single-parameter read-only getter with no output schema, the description names the three data sets it returns and the auth requirement, which is enough for an agent to call it correctly. It could say more about what the response looks like, but the gap is minor.

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 ('The unique farm ID'), so the schema already documents it fully. The description merely restates that farmId is required and adds no format or constraint details 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 (Retrieve) and enumerates the resources returned: active feed inventory, feed purchases, and feed mill logs. This is clear enough that an agent can tell it is a read of feed-related data, though it does not explicitly contrast itself with the write-side sibling log_feed_purchase.

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 only states a precondition (farmId and apiKey) and gives no when-to-use guidance, no exclusions, and no named alternatives despite many sibling get_/log_ tools. An agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the apiKey authorization requirement, which is genuinely useful context not in the annotations, but it says nothing about the optional month filter's behavior or the return 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 with no filler, purpose front-loaded ahead of the authorization requirement. Efficient and easy to parse, though minimal.

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 retrieval tool with no output schema, the description usefully enumerates the returned data categories and the auth prerequisite. Minor gaps remain around month-filter behavior and result size, but nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (farmId as the unique farm ID, month as an optional YYYY-MM filter). The description adds nothing about the month parameter's semantics or format, so baseline 3 applies.

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

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

States a specific verb (Retrieve) plus the resource and the exact data categories returned (expenses, income, cash flow, P&L), which distinguishes it from nearby siblings like get_transactions and get_orders. It does not explicitly name an alternative, 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?

The description only states a prerequisite ('Requires farmId and apiKey authorization') and offers no guidance on when to choose this over get_transactions, get_orders, or other financial-adjacent siblings. There are no exclusions or alternative routing cues.

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 and idempotency profile is fully covered. The description adds one genuinely new behavioral fact — the farmId + apiKey authorization requirement — but says nothing about pagination behavior or result shape despite eight parameters including limit and 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?

Two short, front-loaded sentences with no filler; the purpose leads and the requirement follows. It is arguably too terse for an eight-parameter list tool, but that is a completeness issue rather than a structure flaw.

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 description could reasonably be expected to say more about what a returned hatch batch contains, and it omits any mention of pagination despite having limit/cursor parameters. Annotations carry the safety profile, leaving the description merely adequate rather than complete.

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

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

Schema description coverage is 100%, so every parameter (limit, cursor, status, startDate, endDate, variety, incubator, farmId) is already self-documented. The description echoes only farmId and adds no filter semantics, date format guidance, or interaction rules 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 ("Retrieve incubation and hatch batches"), which is enough to separate it from write siblings like log_hatch_set and log_hatch_result. It does not, however, distinguish itself from the closely-named read sibling get_bird_batches, which an agent could plausibly confuse it with.

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 only guidance is a prerequisite ("Requires farmId and apiKey authorization"), which is a precondition rather than a when-to-use statement. No alternatives are named and no exclusions are given, even though get_bird_batches and get_egg_collections sit in the same domain.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the authorization requirement (farmId and apiKey), which is genuinely new context beyond the annotations. It says nothing about the shape/volume of results, but with annotations carrying the behavioral burden a 3 is appropriate.

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, no filler, and the resource scope is front-loaded before the prerequisite. 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?

For a simple one-parameter read tool, the description covers what is returned (processing logs and freezer inventory) and the auth requirement. It does not describe the return structure or pagination, but the overall coverage is sufficient to invoke the tool correctly, with only minor gaps.

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 one parameter with 100% schema description coverage, so the schema fully documents farmId. The description restates the farmId requirement (and adds an apiKey that is not in the schema, likely an auth header), but adds no meaning about the parameter's format or constraints 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?

The description gives a specific verb ("Retrieve") and names the resources precisely: meat processing logs plus cold storage/freezer inventory. This distinguishes it from the many other inventory/log siblings such as get_feed_inventory and get_egg_collections. It stops short of explicitly naming a sibling to route away from, so it lands at a clear 4 rather than 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 states a prerequisite ("Requires farmId and apiKey authorization") but gives no when-to-use guidance or alternatives among the many other get_* inventory/log tools. An agent must infer on its own when meat inventory is the right call versus feed inventory or bird batches.

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 fully covered. The description adds the audit-oriented purpose but discloses nothing about result scope, pagination behavior, or emptying/ordering, which would have been the value-add here.

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 efficient sentence with the resource front-loaded and no wasted words. It is well-sized, though the brevity comes at the cost of the usage guidance noted above.

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, non-destructive list tool with a fully documented schema and rich annotations, the description is minimally adequate. It omits any note on pagination semantics or filtering, but the annotations and schema carry most of the burden, so nothing critical is missing.

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

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

Schema description coverage is 100%, documenting farmId, limit, and cursor, so the baseline is 3. The description adds no additional parameter meaning such as whether results are scoped strictly to farmId or what cursor iteration returns.

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 (Retrieve) and resource (registered vehicle mileage logs) plus a purpose (tax and expense auditing). It is clear, but it does not differentiate itself from the close sibling get_time_logs, which retrieves a comparable audit-oriented log type.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no indication of how this differs from siblings like get_time_logs or list_vehicles. The intended use case (auditing) is implied rather than stated as a selection condition.

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 fully covered without the description. The description contributes the fact that this is a lookup/mapping operation against a federal regulatory dataset, but adds nothing about result shape, result size, or how partial matches behave.

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

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

A single front-loaded sentence with no filler. The verb and the mapping are stated in the first few words, which is exactly the right shape for a short lookup tool.

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 parameterless-required, read-only lookup with a fully documented input schema and no output schema, the description covers what an agent needs to decide to call it. It could be marginally stronger by signaling that results are a code mapping rather than a full variety record, but 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 limit, query, cursor and category are all documented in the schema itself. The description adds no extra semantics such as which category values pair with which variety types, 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?

The description gives a specific verb ('Resolve') plus a clear resource ('biological poultry and game-bird varieties') and target ('regulatory federal NPIP stock numbers'). It implies the tool maps varieties to regulatory codes rather than enumerating them, which distinguishes it from the nearby list_quail_varieties, though it never names that sibling 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?

There is no statement of when to reach for this tool versus list_quail_varieties or the other bird-related lookups, and no prerequisites or exclusions are mentioned. The agent must infer applicability from the purpose sentence alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the authorization requirement (apiKey), which the annotations do not, but says nothing about pagination behavior despite limit/cursor parameters, nor about what the default 'active/pending' scope means for results.

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 with the purpose front-loaded and filters/authorization following. Efficient overall, though the date-format clause duplicates the schema and the auth sentence could be tighter.

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 a fully described schema and annotations carrying the safety profile, the definition covers purpose, filters and auth prerequisites. Since there is no output schema, return format need not be explained, though pagination semantics via cursor remain unaddressed.

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 all six parameters are already documented, and the description only repeats the date format that the schema already states. It does mention apiKey as an authorization input, but apiKey is not actually a schema property, so that adds ambiguity rather than clarifying a 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 ('Retrieve ... sales orders for the farm'), which an agent can easily separate from the update_order_notes sibling. The scope claim of 'active/pending' is slightly at odds with the status filter in the schema that allows fulfilled/shipped, but the core purpose is 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?

It implies usage by naming the date-range filters and the required farmId/apiKey authorization, which helps an agent know prerequisites. However, it never states when to use this tool versus the other order-related sibling (update_order_notes) or any exclusions.

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 that results are limited to the public directory and names the returned fields, which is modest extra context, but says nothing about result limits, pagination, or empty-result 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 resource and immediately followed by the returned fields. 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 simple, read-only, zero-required-parameter search tool with fully documented schema and annotation-covered safety, the description is nearly sufficient. Only minor gaps remain around result size and whether an empty query returns anything.

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 (query, state) are already fully documented in the schema, and the description restates that searching covers name/bio/specialties. Baseline 3 applies since 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 (search/retrieve) and resource (QuailOS public farm directory), and lists the returned fields. The 'public' qualifier and 'farm directory' scope distinguish it from sibling read tools like get_public_wiki_pages, though no sibling is named directly.

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 a search use case but gives no explicit when-to-use guidance, no prerequisites, and no alternatives. An agent must infer that this is the tool for finding farms rather than, say, beekeeping apiaries.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope ('published', 'public') but says nothing about result volume, pagination, or ordering, which the presence of a cursor parameter makes relevant.

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

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

A single, front-loaded sentence with no filler. The subject matter and action are established in the first few words.

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 endpoint with no output schema and fully documented optional parameters, one sentence is nearly enough. However, it omits the pagination behavior implied by the cursor parameter and the default result count, which an agent would need to page through results 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 all three parameters (limit, query, cursor) are already documented in the schema. The description implies keyword search matching what 'query' does but adds no extra format, default, or pagination semantics beyond the structured data.

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 (Search) and a well-scoped resource (published public QuailOS poultry, game-bird, and hatchery guide articles and walkthroughs). An agent can distinguish this content-search tool from siblings such as get_public_farms, though the description stops short of explicitly contrasting them.

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 to use this tool versus alternatives, nor any prerequisite or exclusion. The only hint is the word 'search', which implies a keyword-driven lookup but leaves the agent to infer the selection conditions.

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 non-open-world, so the safety profile is covered structurally. The description adds the authorization requirement (farmId + apiKey), which is genuine extra context, but says nothing about pagination behavior or result ordering beyond what the schema implies.

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 resource and scope front-loaded and zero filler. It is appropriately sized for a simple list tool, though the second sentence is largely a restatement of a required field already in the schema.

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

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

For a read-only list tool with full schema coverage and annotations covering the safety profile, the description supplies purpose, scope, and auth needs. The absence of any return-shape or pagination note is minor since no output schema exists but the model can infer a list.

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 all six parameters including limit, cursor, status, and date filters are already documented. The description only echoes the farmId requirement and adds no format or semantics 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 (List), resource (support tickets) and scope (created by this farm), so the agent knows what it returns and that it is farm-scoped. It does not explicitly distinguish itself from close siblings like get_ticket_thread or get_feature_requests, which keeps it just 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?

There is no when-to-use, when-not-to-use, or alternative routing. With siblings such as get_ticket_thread (per-ticket detail) and create_support_ticket (creation) present, the description gives no guidance on which to pick, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful auth note ('Requires farmId and apiKey authorization'), but says nothing about return format or pagination behavior. Modest added value against an already-strong annotation set.

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 the core purpose front-loaded, followed by the auth requirement. Efficient and readable, though the second sentence partly restates a parameter already in the schema.

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

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

Adequate for a simple read-only list tool whose annotations cover the safety profile and whose schema covers both parameters. It is missing any mention of return content or pagination, which would help the agent anticipate the response, but nothing essential is absent.

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

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

Schema description coverage is 100%, so both farmId and the optional status filter are documented in the schema. The description's 'active/pending' phrasing loosely maps to the status filter but adds no syntax or format detail beyond what the schema provides, 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 (Retrieve) and resource (farm management tasks) with a scope qualifier (active/pending). An agent can distinguish it from create_task/delete_task/complete_task by the read orientation, though the description does not explicitly name those 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?

It implies the tool is for fetching active/pending tasks but gives no explicit when-to-use guidance or routing to alternatives. With siblings like complete_task and create_task that operate on the same resource, the absence of any exclusion or alternative statement leaves the agent to infer the boundary.

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 authorization requirement ('Requires farmId and apiKey authorization'), which is genuinely useful context, but it stops short of describing volume, pagination, or the shape of the returned thread.

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 the purpose front-loaded and the prerequisite trailing, which is a sensible order. The apiKey clause is slight filler since it maps to no schema field, keeping this just under a 5.

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 two-parameter read-only retrieval with full schema coverage and complete annotations, no output schema required, the description covers what the tool returns at a high level and who may call it. It is nearly complete, missing only output-shape nuance that the absent output schema leaves undefined.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description restates farmId and mentions apiKey, which is not actually a declared parameter, so it adds no meaningful semantics beyond 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?

States a specific verb ('Retrieve') and resource ('full reply history and messages thread of a support ticket'), which is clear and distinguishes the thread view from a list endpoint. It does not name sibling tools like get_support_tickets or reply_to_ticket to sharpen the boundary, 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?

The phrase 'full reply history and messages thread' implies you use this when you need conversational detail rather than a ticket list, and the required identifiers imply a scoped fetch. However, there is no explicit when-to-use/when-not statement, no mention of get_support_tickets as the listing alternative, and no guidance on threading versus replying.

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 fully covered. The description adds nothing further about pagination behavior, result shape, or whether the two resource types are returned together or separately; the phrase 'time clocks' also leaves ambiguity about whether clock entities or clock events are returned.

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 well-formed sentence with no filler, and the verb and resource are front-loaded. It is arguably too terse given the ambiguity it leaves, but nothing is 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?

For a read-only, idempotent, farm-scoped list tool with a fully documented schema and no output schema, the description is minimally viable. It omits what a returned time log contains and how pagination should be driven, but annotations and schema cover the essentials.

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 three documented parameters (farmId required, limit, cursor), so the schema carries the full burden. The description adds no meaning beyond the schema, which is the expected baseline when coverage is complete.

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 ('Retrieve') and names the two resource types (worker time clocks and logged task labor hours), which is more informative than the bare name 'get_time_logs'. It does not, however, distinguish itself from siblings like get_mileage_logs or get_tasks, nor does it clarify the farm-scoped nature of the result.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_mileage_logs for a different log type. The agent must infer the usage context entirely from the tool name.

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 one behavioral nuance — that only 'manual' transactions are returned — but says nothing about pagination or date scoping despite limit/cursor parameters being 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?

A single front-loaded sentence with the verb and resource up front and no filler. It is efficient, though it is arguably too terse to carry usage or return-shape 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 list tool with full schema coverage and rich annotations and no output schema, the description covers the core purpose. It omits pagination behavior and any date/currency filtering semantics, leaving minor gaps for the agent.

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 limit, cursor, and farmId are already documented in the schema. The description adds no additional parameter meaning, which is the expected baseline when the schema does the work.

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 (Retrieve) and a specific resource (manual general ledger transactions) with the covered categories (expense, income, equity). The word 'manual' implicitly separates it from derived reporting tools like get_financial_pnl, but no sibling is 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?

There is no guidance on when to choose this tool versus get_financial_pnl or log_manual_transaction, and no prerequisites or exclusions are stated. The agent must infer usage entirely from the name and the word 'manual'.

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 an authorization requirement (apiKey) not present in annotations, which is useful, but it mentions an apiKey that is not a declared parameter, which is slightly confusing.

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 purpose, with no filler. Size is appropriate for a simple read tool.

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 tool with full annotation coverage, a complete schema, and no output schema, the essentials are present. But it leaves the caller's main ambiguity unresolved: how this differs from get_orders and whether vendor profiles and POs are returned together or separately.

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% for the single farmId parameter, so the schema does the documentation work and the baseline is 3. The description adds nothing about farmId format or scope beyond what the schema states.

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 ('Retrieve') and two concrete resources (purchase orders, vendor profiles), so the agent knows what it returns. It does not, however, distinguish itself from the sibling get_orders, which an agent could easily confuse with the PO half of this tool.

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 no when-to-use context and names no alternative, even though get_orders sits in the sibling list and covers overlapping territory. The only guidance is an authorization prerequisite, not a usage condition.

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 fully covered without the description. The description's real contribution is disclosing the shape of the payload (display names, IDs, description, genotype mappings), which is useful since no output schema exists, but it adds nothing about freshness, caching, or completeness of the registry.

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 front-loaded sentence with no filler; the resource leads and the returned fields follow. The trailing comma-list is slightly dense but every element 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 zero-parameter, read-only list tool with rich annotations, the definition is nearly self-sufficient, and it helpfully names the returned fields in the absence of an output schema. Adding a note on how this list feeds predict_quail_cross would make it fully rounded.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the schema to document and nothing for the description to compensate for. The listed return fields do not correspond to any input 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?

States a specific verb (List) and resource (registered Coturnix quail varieties) plus the exact fields returned. It is unambiguous on its own, but it never contrasts itself with the quail-adjacent siblings find_quail_pairings or predict_quail_cross, so an agent gets no explicit routing help.

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: it reads as a static reference-lookup tool, presumably a prerequisite for predict_quail_cross, but the description never says when to call it or when another tool is more appropriate. No exclusions or trigger conditions are given.

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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds an authorization requirement ('apiKey'), which is useful extra context, but says nothing about return volume, pagination, or ordering.

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 action and resource, with no filler. The only slight noise is the apiKey mention, which does not correspond to a declared parameter and could momentarily mislead.

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, read-only listing tool with rich annotations and no output schema, the description covers action, resource, scope, and auth. Return values need not be explained given no output schema, though pagination behavior would have been a nice addition.

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 there is only one parameter, so the schema already documents farmId as 'The unique farm ID'. The description restates that farmId is required but adds no format or sourcing detail beyond the schema — baseline 3.

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 ('Retrieve registered farm vehicles') and scopes it to mileage logging, which links it to siblings like log_mileage and get_mileage_logs. It stops short of explicitly distinguishing itself from those siblings, so it's clear but not fully differentiated.

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 mileage logging' implies the usage context, so an agent can infer this is a prerequisite lookup before logging mileage. However, it names no alternatives and gives no explicit when-to-use/when-not guidance relative to get_mileage_logs or log_mileage.

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, openWorldHint=false, so the safety profile is covered. The description adds only that confirm (dry-run) and idempotency validation are supported, which is also stated in the schema, and leaves unresolved tension with idempotentHint=false (an idempotency key is accepted, yet the call is declared non-idempotent).

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 the core action front-loaded and no padding. The second sentence is vague rather than wasteful, so it is efficient but not maximally informative.

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 an 8-parameter mutation tool with no output schema, the description omits what a dry-run returns, what happens on validation failure (duplicate idempotency key, invalid hatch date), and confirmation requirements. The rich schema compensates for field-level gaps but not for outcome behavior.

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%, including units, ranges, date format and enum-like location values, so the schema carries the parameter burden and the baseline is 3. The description contributes no additional parameter meaning beyond loosely naming 'confirm' and idempotency.

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 ('Log a new bird inventory census batch'), which is clearly distinct from read siblings like get_bird_batches. However, it does nothing to separate itself from the many other write siblings (log_hatch_set, log_candling, log_egg_collections), so it is clear but not differentiating.

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?

'Supports confirm and idempotency validation' hints at capability but gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as log_hatch_set or log_hatch_result. An agent gets no criteria for choosing this tool over its 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=false and destructiveHint=false, so the write profile is known. The description adds a real behavioral requirement beyond the annotations ("ALWAYS ask for confirmation before writing"), but omits the dry-run preview path exposed by the confirm parameter and says nothing about what record is created or whether re-logging overwrites.

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, purpose first, directive second, no filler. Efficient and front-loaded, though it is arguably too terse to structure the confirmation and dry-run nuances it touches 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?

For an 8-parameter mutation with no output schema, the description covers the core act and the confirmation rule but leaves open the dry-run/commit semantics and whether logging is additive or overwrites an existing candling record for the batch.

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 every parameter including clears, quitters, candleDate, and idempotencyKey is already documented in the schema. The description adds no parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource ("Log egg candling fertility results") and scopes it to "an active batch." An agent can distinguish it from the other log_* siblings by the candling/fertility domain, though it never names the closest alternatives (log_hatch_result, log_hatch_set) to disambiguate.

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 an active batch" implies the prerequisite state, and the confirmation directive gives a procedural rule, but there is no explicit when-to-use vs. -not guidance against sibling logging tools. 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 disclose readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the dry-run/commit behavior and idempotency validation as traits, which is useful context beyond the annotations, but the dry-run semantics are already spelled out in the confirm parameter's schema description, so the added value is modest.

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 the core action front-loaded and no filler. It is appropriately sized, though the second sentence is somewhat vague ('idempotency validation' without specifics).

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 7-parameter mutation tool with no output schema, the description covers the commit/dry-run and idempotency mechanics but omits required-field expectations, default date behavior, and differentiation from the egg-collection reading sibling. Adequate but leaves real gaps an agent must infer from the schema.

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 every parameter (including date, type, confirm, and idempotencyKey) is documented in the schema itself. The description names only 'confirm' and 'idempotency' generically and adds no format, defaults, or constraints beyond what the schema already provides, 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 ('Log') and resource ('daily egg collection count'), so an agent knows exactly what operation it performs. It does not, however, distinguish itself from the sibling read tool get_egg_collections or mention how it relates to log_bird_batch/log_hatch_set style logging tools.

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

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

There is no when-to-use guidance, no mention of prerequisites (farmId required), and no routing to alternatives such as get_egg_collections for reading existing counts. The only usage signal is an implicit dry-run/commit split, which is not framed as 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 only declare write/idempotency/destructive flags; the description adds the important fact that this call mutates a second resource (feed assets inventory), and that confirm toggles commit vs dry-run preview. That goes beyond structured fields. Note a mild tension with idempotentHint=false, which suggests the key-based validation is not guaranteed retry-safe, but this is a clarification gap rather than an outright contradiction.

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 action and its side effect; no filler. The second sentence is slightly vague ("supports ... validation" without saying what validation enforces) but is 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 mutation tool with no output schema, the description covers the primary effect, the dry-run mechanism, and the idempotency concept, while the rich 9-parameter schema handles the rest. Missing: what a dry-run returns and whether permissions or inventory prerequisites are required, both minor given the schema coverage.

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 defines all nine parameters including confirm, idempotencyKey, lbsPerBag defaults, and numeric bounds. The description only names confirm and idempotency without adding format, constraints, or interaction rules, so baseline 3 applies.

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

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

States a specific verb and resource ("Log a feed purchase") plus the key side effect ("automatically increment feed assets inventory"), which distinguishes it from read-only siblings like get_feed_inventory. It does not explicitly name or contrast with other log_* siblings, but the resource is narrow enough that an agent can place it correctly.

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 mentions "confirm and idempotency validation," which implies a dry-run-first workflow and a safe-retry path, but it never states when to use this tool versus alternatives or what conditions require idempotencyKey. Usage is implied rather than spelled out.

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 a non-read-only, non-destructive, non-idempotent write with no confirmation semantics, and the description adds genuinely new behavioral context: an explicit human-confirmation requirement before writing and disclosure of a side effect (optionally creating a bird batch). It still does not explain what stats are calculated or how idempotencyKey interacts with retries.

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, front-loaded with the core action and followed by the operational constraint. No filler, and the confirmation warning is placed last for emphasis where it belongs.

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 an 8-parameter mutation tool with no output schema, the description covers the essential behaviors (what it writes, the side effect, and the confirmation gate) and leaves parameter detail to a fully covered schema. It is slightly thin on return-value expectations for the stats calculation, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including confirm's dry-run semantics and createBirdBatch's default. The description only restates the optional bird-batch behavior, adding nothing the schema lacks, 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+resource (log final hatch count) and enumerates the sub-actions: calculating stats and optionally creating a bird batch. It implicitly contrasts with the sibling log_hatch_set (which starts a batch) by framing this as 'complete a batch', but it never names that 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?

'Complete a batch' implies this is the finalization step after log_hatch_set, which gives implied usage context. However, there is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as log_bird_batch, which the tool can itself trigger.

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 genuine behavioral context beyond them: that lockdown/hatch dates are derived automatically, and that a confirmation step is mandatory before the write commits. It stops short of explaining what the write creates or how the derived dates are computed.

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 filler, and the primary action is front-loaded ahead of the confirmation constraint. Nothing is redundant or 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 9-parameter mutation with annotations covering the safety profile, full schema coverage, and no output schema, the description is nearly sufficient. The one notable gap is that it doesn't mention the dry-run preview path via the confirm parameter, which is central to how this tool is safely invoked.

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 every one of the 9 parameters is already documented, including the confirm dry-run flag, setDate constraints, and idempotencyKey. The description adds no parameter-level meaning beyond that, 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?

The description names a specific verb and resource ("Start a new incubation batch") and adds a distinctive scope detail (auto-calculating lockdown/hatch dates). An agent can distinguish it from log_hatch_result or get_hatches, though the description never names those siblings explicitly to sharpen the contrast.

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 ask for confirmation before writing" is a real usage directive that tells the agent how to sequence the call, but it says nothing about when to choose this tool over log_hatch_result, get_hatches, or log_eggs. Usage is implied by the purpose statement rather than explicitly framed against alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is largely covered. The description adds the non-obvious requirement to confirm before writing, which is genuinely useful context, but it says nothing about the non-idempotent retry implications of a write tool or the relationship between the confirmation rule and the `confirm` dry-run parameter.

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, both of which earn their place: one declares the purpose, one declares the mandatory confirmation workflow. Nothing is padded and the purpose 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?

There is no output schema, and for a 13-parameter write tool the description is thin: it omits what a committed inspection affects, how dry-run differs from commit, and how it relates to neighboring beekeeping logging tools. The fully documented schema compensates for parameter-level gaps, keeping this at minimum viable.

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% across all 13 parameters, so the schema already documents each field including the confirm dry-run semantics and idempotencyKey. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Log a ... hive inspection') with a scope qualifier ('detailed beekeeping'), which is clearly distinguishable from sibling writes like log_honey_harvest or log_varroa_treatment. It stops short of explicitly contrasting those adjacent siblings, so it is clear but not fully differentiated.

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 ask for confirmation before writing' is a concrete operational guideline tied to the write action, which is more than most definitions offer. However, it gives no guidance on when to use this tool versus log_varroa_treatment, log_honey_harvest, or update_queen_status, so usage selection is left to inference.

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, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds important behavioral context beyond annotations: the requirement to always ask for confirmation before writing, and the optional inventory side effect.

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, front-loaded with the core action and the optional side effect. Every sentence earns its place: the first states the purpose, the second states a critical invocation constraint.

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 10-parameter write tool with no output schema, the description covers the essential purpose and the confirmation requirement. It relies on the 100% schema coverage for parameter details, which is reasonable, though it could mention the hiveId/yardId dependency or dry-run confirm behavior to be fully self-contained.

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 ten parameters, including the confirm, addToInventory, and idempotencyKey options. The description only touches on 'add directly to stock inventory' (addToInventory) and adds no syntax or format details beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Log honey extracted and optionally add directly to stock inventory.' It is clear what the tool does and the optional inventory side effect, but it does not explicitly differentiate itself from any sibling tool (e.g., log_hive_inspection or log_varroa_treatment).

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 no guidance on when to use this tool versus alternatives in the sibling list. 'ALWAYS ask for confirmation before writing' is a behavioral instruction, not a usage condition that helps an agent choose between 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 declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description need not restate it. It does add two genuinely useful behaviors not in the annotations: a confirm flag enabling dry-run preview before commit, and idempotency validation. However it never says what a dry-run returns, whether a missing idempotencyKey risks duplicates, or why idempotentHint=false coexists with 'idempotency validation'.

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 the core action front-loaded and no filler. It is efficient, though the second sentence is a feature list rather than the most decision-relevant information (the manual-vs-specialized boundary would have been a better second sentence).

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 an 8-parameter mutation tool with no output schema and no annotation coverage of the dry-run path, the description is thin: it omits what confirm=false returns, how idempotencyKey interacts with repeat calls, and the relationship to get_transactions. The 100% schema coverage on inputs prevents this from being worse than minimally adequate.

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 8 parameters including the confirm dry-run semantics and the amount bounds. The description only gestures at 'confirm and idempotency validation' and adds no format, default, or edge-case 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 concrete verb (log) and resource (a manual income/expense/equity transaction), and the word 'manual' implicitly separates it from the automated domain-specific loggers in the sibling list (log_feed_purchase, log_eggs, log_mileage). It stops short of naming those siblings or stating the boundary explicitly, so an agent must infer when a transaction is 'manual'.

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

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

There is no when-to-use or when-not-to-use guidance. An agent is left to infer from the adjective 'manual' that this is the fallback for transactions not covered by the specialized log_* siblings, and nothing tells it whether get_transactions is the read counterpart or what prerequisites exist.

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 establish the write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: IRS rate calculation tied to the trip date and a confirm/idempotency mechanism. The 'idempotency validation' phrasing sits against idempotentHint=false, but the opt-in idempotencyKey parameter explains it, so this is not a true contradiction.

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 capability front-loaded and no filler. The second sentence ('Supports confirm and idempotency validation') is slightly vague but still earns its place by flagging the dry-run mechanism.

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 an 11-parameter write tool with no output schema, the description covers the essential behaviors (IRS calculation, dry-run/commit, idempotency) and annotations cover the safety profile. It stops short of explaining what a dry-run preview returns or what side effects a commit produces, leaving some gaps for a mutation tool.

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 all 11 parameters are already documented, including confirm (dry-run vs commit), idempotencyKey, and the enum category. The description reinforces the date/IRS and confirm concepts but adds no syntax or format detail beyond what the schema already supplies, 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 (log) applied to a specific resource (vehicle travel trip) and adds the differentiating feature of automatic IRS rate calculations. It implicitly separates itself from the read-only sibling get_mileage_logs, though it never names that sibling 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 mention of 'confirm' and 'idempotency validation' hints at a dry-run-then-commit workflow, but there is no explicit when-to-use guidance, no statement of prerequisites, and no reference to alternative tools. Usage is left to inference from the parameter 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=false and destructiveHint=false, so the write-but-not-destructive profile is covered. The description adds a meaningful behavioral rule beyond the annotations: a mandatory confirmation step before committing. It still omits what happens on failure, duplicate handling (relevant given the unmentioned idempotencyKey), and permission 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?

Two short sentences with zero filler; the action statement comes first and the confirmation constraint follows immediately. 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 an 8-parameter mutation tool with full schema coverage and an explicit non-destructive annotation, the description covers the essential action and the critical workflow constraint (confirmation). It is missing only secondary context such as response/failure behavior and idempotency handling, and there is no output schema requiring explanation.

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 all eight parameters (including confirm's dry-run semantics and idempotencyKey) are already documented in the schema. The description adds no extra meaning about product, dose, dates, or confirmation flow. Baseline 3 is appropriate when the schema does all the work.

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 (Record) plus a concrete resource (mite treatment chemical or acid application), which clearly separates it from sibling logging tools like log_hive_inspection or log_honey_harvest. It does not explicitly name or exclude any sibling, but the named resource is specific enough that no confusion is likely.

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 one actionable precondition – ALWAYS ask for confirmation before writing – which is genuine usage guidance for a write tool. It says nothing about when to prefer this over alternatives such as log_hive_inspection, and no exclusions or context conditions are given, 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description adds useful scope by naming what is verified (handshake responsiveness, platform status) rather than plain connectivity, but says nothing about latency, failure behavior, or what a result indicates.

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 listing the three things verified, with no filler or restatement of the name. Nothing could be trimmed without losing meaning.

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

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

For a zero-parameter read-only diagnostic, the description covers what an agent needs to decide to call it. Without an output schema, however, it does not hint at the return shape (status object, message, version, latency), which would be the only remaining useful detail.

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 per the rubric the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter behavior for a parameterless call.

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

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

The description gives specific verbs and objects — verifying connectivity, handshake responsiveness and platform status — so an agent knows exactly what the tool checks. It needs no sibling differentiation since no other diagnostic/health tool exists in the list. Slightly short of 5 because 'platform status' is broad and the checks aren't tied to any output or failure signal.

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: naming the connectivity/handshake checks suggests this is the tool to call to confirm the server is reachable before or during other work. There is no explicit 'use when...' statement, no mention of calling it before dependent operations, and no guidance on how often it is safe to call.

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 that this is a safe, read-only, idempotent, open-world calculation with no destructive effects. The description adds domain scope and enumerates output categories, but it does not disclose assumptions, calculation limits, or how breed-level coverage works despite mentioning '310 avian breeds'.

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 a single front-loaded sentence with no wasted words. It states the calculation scope and output categories compactly.

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 an 11-parameter optional-input calculation tool, the schema and annotations already carry most operational detail, and the description broadly communicates what the tool returns even without an output schema. The main gap is that it mentions 310 avian breeds while the schema exposes no breed parameter, which could create a slight mismatch in expectations.

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 11 parameters, their enums, defaults, and mode-dependent behavior. The description adds no parameter-level meaning beyond the schema, which is the baseline 3 for fully covered 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 names a specific verb ('Calculate') and scope ('chicken/quail flock sizing, incubation guidelines, weekly feed, spaces, and costs'), clearly distinguishing it from sibling logging, retrieval, and pairing tools. An agent can tell this is a planning/calculation tool 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 description explains what the tool computes but gives no when-to-use guidance, no conditions for choosing it over alternatives, and no exclusions. Unlike operational siblings such as log_eggs or get_bird_batches, the intended planning scenario is only implied by the tool name.

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 a closed-world scope, so the safety profile is fully covered. The description adds only that the output is a probability distribution/percentage, without noting accuracy, determinism of results, or error behavior for unknown varieties — modest value over 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?

A single tight sentence with the verb and resource front-loaded and no wasted words. Slightly long relative to the small surface area but nothing that should be cut.

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, so the description usefully names the return content (probability distributions and percentages). For a simple two-parameter read-only calculator with full annotation and schema coverage, this is essentially complete, though it could say more about the shape of the results.

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 both sire and dam are fully documented (name or unique ID, case-insensitive). The description restates the sire/dam relationship but adds no syntax or format detail beyond the schema; 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 ("Calculate") and a precise resource ("offspring plumage color probability distributions and percentages") tied to a defined input (sire x dam cross). This is far more specific than a tautology and clearly distinct from siblings like list_quail_varieties or find_quail_pairings, though 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?

The clause "when crossing a specific sire and dam variety" implies the usage context but gives no when-to-use vs when-not guidance or reference to sibling tools. An agent can infer the scenario but gets no explicit routing help.

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 this is a non-read-only, non-destructive, non-idempotent write. The description adds value beyond that: the ticket must be 'open' (a constraint absent from annotations) and that confirmation is required before writing. It doesn't mention the dry-run/confirm param or idempotency behavior in prose, but the added constraint and confirmation rule justify a 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?

Two short sentences, front-loaded with the core action and followed by the critical confirmation instruction. Every sentence earns its place with zero waste.

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 write tool with full schema coverage and a set of safety annotations, the description covers the key constraints: open-ticket scope and mandatory confirmation. It omits the dry-run/commit semantics of the confirm parameter and any note on return behavior, leaving minor gaps.

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 every parameter (farmId, ticketId, message, confirm, idempotencyKey) is already documented in the schema. The description adds no syntax, format, or value details beyond that, 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?

The description states a specific verb and resource ('Add a reply message to an open support ticket'), so the agent knows this is a write operation that posts a message. It does not, however, name the sibling tools it should be distinguished from (e.g. get_ticket_thread, create_support_ticket), so it falls short of full 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?

'ALWAYS ask for confirmation before writing' gives a workflow instruction, implying the agent should interact with a user before committing. It gives no explicit when-to-use vs alternatives or prerequisites beyond this, so usage guidance is implied rather than comprehensive.

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 this as a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that — the default append mode with a timestamped 'via AI' marker — but says nothing about the confirm/preview gate, the replace-overwrite risk, or the idempotencyKey dedupe behavior, all of which live only in 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?

A single tight sentence with no filler, and it front-loads the most distinctive behavior (timestamped append by default). It is efficient, though the fragmentary phrasing means it never frames the overall operation.

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 7-parameter mutation tool with a preview/commit workflow, a replace-overwrite confirmation gate, and an idempotency key, one sentence is far too thin. Since no output schema exists, an agent gets no sense of what a successful edit returns or what the preview mode yields.

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 every one of the seven parameters is already documented with enums, defaults, and conditional requirements (confirmReplace for replace mode). The description reinforces only the append default and adds no syntax, format, or constraint 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?

The description conveys a specific action (appending a timestamped note) and a default behavior, but never names the resource it operates on — an agent must infer 'order' from the tool name. It reads more like a default-behavior footnote than a purpose statement, so the verb+resource pair is only half stated.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. farmId/orderId needed), and no reference to any alternative. The one sibling list contains no competing note-editing tool, so some of this burden is on the agent, but the description offers nothing about when this call is appropriate.

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 this is a write (readOnlyHint=false), non-destructive, and non-idempotent. The description adds the confirmation-before-writing requirement, which is useful behavioral context beyond annotations, but says nothing about what the write affects, reversibility, or how the confirm/idempotencyKey parameters alter 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 purpose followed by the safety instruction, with no filler. The phrase 'live ... metadata settings' is slightly vague, but the structure wastes nothing.

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

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

With rich annotations and a fully documented 8-parameter schema, the description needs only to frame intent and safety, which it does. It leaves the dry-run/confirm and idempotency semantics entirely to the schema, so it is adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the status enum and the confirm dry-run flag. The description only loosely gestures at the payload ('queenright and breeder metadata'), so it adds marginal value over structured data, which is the baseline case for a 3.

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 (Update) and resource (queenright and breeder metadata settings of a hive), and the term 'queenright' ties it clearly to the queen-status enum in the schema. It does not name a sibling to distinguish from, but nothing in the sibling list overlaps this domain, so ambiguity is low.

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 ask for confirmation before writing' gives an operational rule for invoking it, which is genuine usage guidance. However, it never states when this tool is appropriate versus alternatives (e.g., log_hive_inspection, which also touches hive state), so the when/when-not dimension is only implied.

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