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

Annotations already indicate this is a mutating (readOnlyHint=false) but non-destructive (destructiveHint=false) operation. The description adds little behavioral context beyond that, such as whether marking an identifier as primary replaces another primary, how duplicates are handled, or what side effects occur.

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 filler. It names the action, the resource, and the relevant identifier types without wasting 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?

The schema covers the parameters and the description states the core operation, which is enough for straightforward calls. However, there is no output schema and no description of behavior around optional inputs like is_primary or farm_id, so the context is adequate but not fully 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 input schema already explains all five parameters. The description's parenthetical list of identifier types mirrors the enum in the schema and adds no extra meaning beyond that 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 action ('Add an identifier') and a clear resource ('to an animal'), and it enumerates the identifier types supported. This clearly communicates the tool's purpose, though it does not explicitly name sibling tools like remove_identifier or list_identifiers 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?

The verb 'Add' implies the primary use case: attaching a new identifier to an animal. However, the description provides no explicit guidance about when not to use it or when to prefer related tools such as remove_identifier or find_animal_by_identifier.

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

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

Annotations already indicate this is a mutating, idempotent, non-destructive operation. The description adds critical behavioral constraints: preserve request_id, bundle, and confirmation_hash; never generate the hash; never silently obtain and approve a fresh preview. This goes beyond what annotations provide and clarifies the expected call pattern. It does not contradict any annotation.

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

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

Three sentences with no wasted words. The purpose is front-loaded, the critical constraint is stated clearly, and the stale-preview caveat is included. Everything 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 complex tool with many nested objects and no output schema, the description covers the core workflow but omits details like return values, error conditions, or the farm_id parameter. The annotations handle idempotency and destructiveness, and the description covers the approval requirement, but an agent might still be unsure about what to expect after a successful call. Given the complexity, more could be expected, though the main purpose and constraints are clear.

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

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

Schema description coverage is only 25%, so the description should compensate for undocumented parameters. It does give meaning to the three required parameters (request_id, bundle, confirmation_hash) by tying them to the approval workflow, but it does not explain the structure of the bundle or other parameters like farm_id. The mention of 'preserve' adds semantic value to confirmation_hash and request_id, but the bundle's internal fields remain largely undefined. This is adequate but not comprehensive.

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 action ('Save one complete producer-approved birth bundle') and clearly distinguishes it from the preview step by referencing 'preview' and 'fresh preview'. It is unambiguous that this is the confirmation/save tool, separate from preview_birth_event.

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

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

Explicitly states the precondition ('Only call after the producer explicitly approves the exact preview') and the exclusion ('A stale preview must be reviewed again'). It implies the alternative is the preview tool, and gives clear when-to-call guidance without needing to name the sibling explicitly.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no behavioral details beyond restating that a record is created, such as required permissions, default farm behavior, duplicate handling, or side effects. There is no contradiction, but no value beyond the annotations.

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

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

The description is short and front-loaded, with no wasted words. However, for a tool with 10 parameters and several sibling creation tools, it is under-specified rather than efficiently structured; a bit more structure would materially help.

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

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

Given the tool complexity and absence of an output schema, the one-line description is incomplete. It does not explain what happens when no optional fields are provided, how farm defaults work, what the response is, or how this tool relates to nearby creation tools.

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

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

Schema description coverage is 100%, and every parameter is individually documented with examples and enum meanings. The description itself adds no parameter-level semantics, so it stays at the baseline without needing to compensate for schema gaps.

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

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

The description clearly states a specific action and resource: 'Create a new animal record on the farm.' It is not a tautology and is obviously distinct from update/delete tools, though it does not explicitly distinguish itself from close siblings like create_record or confirm_birth_event.

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 about when to use create_animal versus alternatives such as create_record, update_animal, or confirm_birth_event. No prerequisites, exclusions, or selection criteria are mentioned.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description goes well beyond that by disclosing the propose-then-review-then-start lifecycle, the no-data-recorded side effect, widget arrangement constraints, and the EID-scanning reminder. This is exactly the kind of behavioral context that annotations lack.

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?

Every sentence carries content, and the purpose is front-loaded. It is somewhat dense as one paragraph with several rules (widget types, sizes, order, cap), so it could be tightened or bulleted, but nothing is filler.

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

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

For a complex widget-builder tool with no output schema and only two annotations, this description is unusually complete on input construction and lifecycle. It does not describe the API response after proposing or explicitly cover optional parameters, but those are documented in the schema and the flow is implied, leaving 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?

Schema covers all six parameters, so baseline is 3. The description adds substantial meaning for widgets: each type's UI behavior, options fields, size rules, ordering, and ~6-widget cap. It adds less for name, farm_id, group_name, record_type, and new_animal_fields, which rely on the schema, so a 4 rather than 5.

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

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

Opens with a specific action and object — 'Propose a chute-mode work session' — and immediately clarifies that it creates only a PROPOSED session, distinguishing it from record-writing tools and update/list chute-session tools in the sibling set.

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 establishes clear use context ('from a description of the day's work') and an important boundary ('proposing never records any data by itself'), implying this is not create_record or update_chute_session. It does not explicitly name an alternative or state when not to use this tool, so it stops short of a 5.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description ('Create a new group') is consistent with a non-read, non-destructive operation. However, the description adds no behavioral context beyond what annotations already signal, such as idempotency or side effects.

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 efficiently communicates the core purpose while leaving parameter details to 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 simple 3-parameter create operation with a fully documented schema and consistent annotations, the description is largely sufficient. It does not describe the return value or expected response format, but given the low complexity and no output schema, this 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 coverage is 100%, so parameters are documented in the schema. The description adds no parameter-level meaning beyond 'on the farm', which aligns with the farm_id property. Baseline score of 3 is appropriate since the schema carries the parameter documentation burden.

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 action ('Create') and resource ('a new group') with a farm scope. It is clear and differentiates from sibling tools like list_groups, update_group, and delete_group, though it adds little beyond the tool's name.

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?

No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as update_group, nor does it clarify prerequisites or conditions like whether a default farm must be set. Usage is only implied by the verb 'Create'.

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 description adds the behavioral trait 'immutable', which is not present in the annotations. It also conveys a policy constraint ('producer-approved', 'do not invent') that affects how an agent should use the tool. Combined with idempotentHint=true and destructiveHint=false, this gives a fuller picture. It does not mention auth requirements or return behavior, but the key immutability fact is valuable.

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

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

Two sentences, no filler. The core purpose is in the first sentencecars, and the critical constraint is in the second. Every word contributes to correct invocation.

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 4 parameters.težáno, no output schema, and 0% schema coverage, the description is lean. It clearly handles the 'steps' parameter, but name, version, and farm_id semantics are left entirely to inference from their names. Given the simplicity of those parameters, the gap is moderate—not severe—but a short phrase like 'unique version label' would have rounded it out.

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

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

Schema description coverage is 0%, so the description must compensate. It only elaborates on 'steps' (exact named steps, do not invent), but provides no added meaning for 'name', 'version', or 'farm_id'. The schema gives basic types and constraints only. The description fails to clarify what constitutes a valid name/version or how farm_id relates to the current context.

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

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

The description clearly states the action 'Create' and the resource 'producer-approved immutable farm protocol version'. It also specifies the input source ('exact named steps'), which distinguishes it from other create tools like create_ration or create_record. The qualifiers 'immutable' and 'producer-approved' make the purpose unambiguous.

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

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

The description gives strong contextual guidance: only use this tool when there is a producer-approved set of steps, and do not invent steps. While it doesn't explicitly name alternatives, the instruction to avoid inventing care steps clarifies a boundary. The 'from the exact named steps provided' phrase establishes the expected input 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?

Beyond the generic annotations, the description discloses important behavioral traits: the tool is STRUCTURE ONLY and will not validate nutrition, it must never invent amounts, and all group assignments are 'created INACTIVE' pending activation in the app. This gives the agent critical knowledge about side effects and limitations that annotations alone do not convey.

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

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

The description is tight and front-loaded: purpose first, then the STRUCTURE ONLY constraint, then the inactive-assignment behavior. Every sentence carries meaningful information and none is wasted on restating schema or annotations.

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

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

For a create tool with no output schema and five parameters, the description covers purpose, units, parameter framing, safety limits, and activation behavior. The only mild gap is that it does not describe what the tool returns or whether it returns the created ration, but this is not essential for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds meaning by framing ingredients as 'per-head-per-day pounds' as the canonical basis and by emphasizing that amounts must come from the user, not be invented. This adds useful semantic context beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Create a feed ration the user has already decided on,' and immediately clarifies the format ('named recipe in per-head-per-day pounds') plus optional group assignments. This clearly distinguishes it from sibling read tools like list_rations and get_ration and from other create 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?

The description gives an explicit precondition ('the user has already decided on') and an explicit when-not-to-use boundary: 'never formulate, balance, or validate nutritional adequacy... if asked what or how much to feed, decline and refer the user to their nutritionist.' This leaves no ambiguity about when the tool should or should not be invoked.

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 correctly indicate destructiveHint=false and readOnlyHint=false (implying mutation). The description has no contradiction but does not add much beyond the annotation—except the critical side-effect that unattached records are invisible. This extra constraint is valuable, but other behaviors like required permissions or response format are not disclosed, so 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?

The description is one sentence plus the critical warning. It is concise, front-loads the action and key constraint, and every word adds value. No filler.

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

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

Given the tool has 7 params, 100% schema coverage, and no output schema, the description covers the essential usage guidance (the dependency on UUIDs) and the purpose. It could mention what happens on success/failure or permissions, but it's sufficiently complete for an agent to call it 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 coverage is 100%, so parameters are fully described in the schema. The description adds the critical relationship between animal_ids/group_ids and the need to pass at least one, which is not fully clear from schema defaults. That adds semantic value, but not a huge amount 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?

The description clearly states 'Create a record... and attach it to animals and/or groups' with a concrete event type list (feeding, health treatment, movement). It explicitly distinguishes the target resource (record) and its associations, clearly differentiating from sibling tools like update_record or delete_record.

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 provides a clear usage context: 'Always pass at least one resolved animal or group UUID — a record attached to nothing will not appear in any animal's history.' This states a critical condition for use, but does not explicitly mention when not to use or mention alternatives. Still, the constraint is actionable and guides the agent to avoid misuse.

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 destructiveHint=true and readOnlyHint=false, establishing that this is a destructive write operation. The description adds a meaningful behavioral nuance by specifying 'soft delete', indicating the record is not permanently removed. This goes beyond the generic destructive hint and helps the agent understand the operation's reversibility, though it does not detail side effects on related data.

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 sentence with no unnecessary words, directly stating the operation and its soft-delete nature. It is front-loaded with the action and resource, making it immediately scannable and efficient.

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

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

For a simple delete tool with two parameters, no output schema, and destructive annotations, the description covers the essential details: what it does and that it is soft. It could mention whether soft-deleted animals remain queryable, but the combination of clear purpose, schema, and annotations makes it sufficient for correct invocation. Minor additional context would elevate it further.

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

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

The input schema provides 100% coverage with descriptions for both farm_id and animal_id, including types and optionality. The tool description adds no additional parameter-level meaning beyond what the schema already states. With full schema coverage, the baseline of 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 clearly states the action ('Delete') and the resource ('animal record'), and specifically notes 'soft delete', which distinguishes it from hard-delete tools and sibling tools like delete_record or delete_group. The verb+resource structure is unambiguous and the name aligns perfectly with the description.

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 usage (when you need to soft-delete an animal), but it does not provide explicit guidance on when to prefer this over alternatives such as delete_record, farm_archive, or remove_identifier. No prerequisites, exclusions, or when-not-to-use conditions are mentioned. The purpose alone suggests the appropriate context, but it is not explicitly 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 already indicate destructiveHint: true, but the description adds critical nuance by clarifying this is a soft delete (archive) and that the group can be restored. This goes beyond the bare annotation and sets accurate expectations about reversibility, which is valuable for an agent deciding whether to invoke it. There is no contradiction; the description enriches the behavioral 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?

The description is extremely concise, using two short sentences with no fluff. It front-loads the core action ('Archive (soft delete) a group') and immediately follows with the key consequence (hidden from active list, restorable). Every word earns its place, and the structure makes it easy to scan quickly.

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 two parameters and no output schema, the description covers the essential effects: the soft-delete nature, the visibility change, and reversibility. It does not mention potential side effects like cascading actions or permissions, but given the simple scope and the presence of annotations, it is adequately complete. Adding a pointer to restore_group would have made it more complete, but it is not a significant 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% and both parameters (group_id and farm_id) have clear descriptions in the schema. The tool description adds no additional parameter-level meaning beyond the schema, so it does not exceed the baseline. The description does not explain how to obtain group_id or any format requirements, but the schema already covers that.

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

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

The description clearly states a specific verb ('Archive') and resource ('a group'), and explicitly notes it is a soft delete, which distinguishes it from a hard delete. It also mentions the effect (hidden from active list) and reversibility, making the purpose unmistakable. This is far from a tautology and immediately differentiates from other delete tools like delete_record or delete_animal.

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 the tool is for archiving groups and mentions it can be restored, but it does not explicitly state when to use this tool versus alternatives such as restore_group or other delete tools. It does not mention exclusions or provide routing guidance to sibling tools, leaving the agent to infer usage context from the name and behavior. A more explicit note about using restore_group for undo would have been helpful.

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 destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds 'soft delete' as behavioral context beyond the annotations, which is useful, but it does not describe consequences such as reversibility, visibility in future list_records calls, or associated side effects.

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 compact sentence with no filler. It front-loads the action and immediately clarifies the soft-delete behavior terms. 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 two-param tool with annotations and a 100%-documented schema, the description is minimally viable. However, it is thin on operational context: it does not explain what 'soft delete' means for downstream behavior, what happens to related data, or when this tool should be preferred over other delete operations. Given the absence of an output schema)Skip

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%: record_id is clearly documented as 'The UUID of the record to delete' and farm_id is described as optional with a default. The description itself adds no parameter-level meaning beyond saying the tool deletes a record, so it relies on the schema, which is acceptable.

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 clear verb and resource: 'Delete (soft delete) a record.' The parenthetical adds the important nuance that deletion is not a hard delete stolen from the name. It is not as strong as explicitly differentiating from sibling delete tools, but it is unambiguous about what the tool operates on.

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?

No guidance is provided about when to use this tool instead of alternatives such as delete_animal, delete_group, or update_record. There is no mention of prerequisites, sequencing, or conditions under which soft-delete is appropriate, so the agent must infer usage entirely from the name and schema.

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

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

With no annotations, the description must fully disclose behavioral traits. It reveals that downloads write a private ZIP file at output_path and that private conversations and credentials are excluded. However, it doesn't mention that archive creation is likely asynchronous (requiring status polling), whether existing files at output_path are overwritten, what the response for each operation looks like, or any permission requirements. These are critical for correct invocation, especially for a tool with five distinct operations.

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, dense sentence that efficiently covers the tool's capabilities and key side effects. It is not padded, and the critical fact about writing a ZIP is included. However, it lacks structure (e.g., bullet points for operations) and buries the exclusions at the end. Still, it is concise and front-loads the main actions.

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

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

Given the tool has five operations, no output schema, and no annotations, the description is far from complete. It doesn't explain the lifecycle (create → status → download), the purpose of export_id, how to handle async operations, or what happens on cancel. It also doesn't describe the response structure for list or status. An agent would need to infer too much from operation names and parameter names alone, risking incorrect calls.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It only mentions output_path (for downloads) and implicitly operation via the action list. It does not explain farm_id (which farm to archive) or export_id (how to reference an archive for status/cancel/download). The operation enum is self-explanatory, but the mapping between operations and required parameters is absent. This leaves significant gaps for the agent.

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

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

The description clearly states the tool's role: managing farm archives with five operations (create, list, inspect, cancel, download). It distinguishes itself from siblings by focusing exclusively on archives, and mentions the resource (farm archive) and actions. However, the word 'inspect' in the description does not exactly match the 'status' operation in the enum, creating minor ambiguity about what the operation actually does.

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

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

The description provides some usage context: no subscription needed, downloads write a private ZIP at output_path, and certain data is excluded. It doesn't explicitly compare to alternatives, but there are no sibling archive tools, so this is acceptable. It doesn't state when to use this vs. other tools for data export, nor does it describe prerequisites like having a farm_id. The guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals the key create-on-miss side effect but omits details about farm context requirements, permissions, idempotency, or failure behavior when no animal is found and creation is not possible.

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 zero filler. Every word contributes to clarifying the tool's core action, making it appropriately sized and easy to parse.

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

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

For a tool with no output schema and no annotations, the description is too terse. It does not specify what the tool returns, how creation side effects are indicated, or what happens when no matching animal exists, leaving a critical behavioral gap for an 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 the baseline is 3. The description adds only the expansion of the EID acronym and does not enrich the meaning of farm_id or provide any detail beyond what the schema already 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?

The description uses a specific verb ('Find or create') with a clear resource ('animal') and a unique lookup key ('EID'). This distinguishes it from sibling tools like get_animal and create_animal, which handle retrieval and creation as separate operations.

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 'Find or create an animal by EID' implies the tool is appropriate when you need to locate an animal by its electronic ID and create it if absent. However, it gives no explicit guidance on when to prefer this over get_animal or create_animal, or when not to use it.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds no behavioral details beyond that, such as error behavior, return shape, or permission requirements, so it provides no additional transparency value.

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 efficient sentence with no wasted words. The core action, target resource, and selection key are all front-loaded and immediately actionable.

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-by-ID tool with one required parameter and readOnlyHint annotations, the description is nearly complete. The optional farm_id context is left to the schema, but the overall definition is adequate for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with both animal_id and farm_id documented in the input schema. The description reinforces that animal_id is the UUID, which aligns with the schema, but it does not add new meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Get') with a clear resource ('details about a specific animal') and a precise identifier scope ('by its UUID'). This distinguishes it from broader tools like list_animals and from find_animal_by_identifier, which targets animals by a different identifier 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?

The description clearly implies the tool should be used when the agent has an animal UUID and needs that animal's details. It does not explicitly mention alternatives or when not to use it, but the UUID scoping provides enough context for selection among 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 this as read-only, idempotent, and non-destructive. The description adds a meaningful behavioral constraint: only evidence the current user may access is returned, which is useful context beyond the annotations. There is no contradiction with the annotations.

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

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

The description is a single sentence with no filler or redundant phrasing, and it front-loads the main action. It is concise, though the brevity leaves room for more explanatory content.

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 getter with read-only annotations, the description is close to adequate. However, it does not clarify what 'evidence' means, whether the optional farm_id is needed for disambiguation, or what the return payload looks like—especially since no output schema is present.

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

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

Schema description coverage is 0%, and the description does not compensate by explaining either parameter. event_id is required but not described, and farm_id's optional role is completely unexplained. The description adds no parameter meaning beyond the schema's field names.

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 ('a saved birth event and evidence'), which is clear enough to identify the tool's core purpose. It adds an access-scoping qualifier ('the current user may access'), but it does not explicitly distinguish itself from siblings like list_birth_events or get_birth_history_evidence.

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 about when to use this tool versus alternatives. It does not mention list_birth_events for listing or get_birth_source_evidence/get_birth_history_evidence for evidence-specific retrieval, so the agent must infer usage from the tool name and minimal 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?

The annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable nuance beyond the annotations by clarifying that the evidence is a review proposal and not a DNA confirmation or an automatic parentage write. There is no contradiction between the description and annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the action and scope, and the second adds a necessary negative guarantee. Every sentence contributes to the agent's understanding.

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 no output schema, the description covers the core content (exposures, membership, movement) and the important caveat that the evidence is a proposal, not confirmation. It could be more explicit about the response shape or pagination, but the annotations and description together are sufficient for deciding whether to call it.

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

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

With schema description coverage at only 33%, the description carries more weight. It clarifies that the query is keyed by dam and birth date and that the evidence is dated, but it does not explain farm_id defaulting or add detail about the exact meaning or format of the required parameters beyond their schema names and patterns.

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

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

The description opens with a clear read verb and names the resources: dated exposures, historical membership, and movement comparisons, scoped to a dam/birth date. It also states what the tool is not (DNA confirmation or automatic parentage write), but it does not explicitly distinguish it from siblings like get_birth_source_evidence.

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 clear context for when to use the tool: for presumed-sire evidence review keyed by dam and birth date. The explicit 'never DNA confirmation or an automatic parentage write' is a useful when-not signal, though it does not name alternative tools such as get_birth_source_evidence or confirm_birth_event.

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. The description adds the behavioral detail that it returns 'zero-to-many planned birth windows,' which is useful context about the response shape. It doesn't disclose anything about permissions, defaults, or error behavior, but with strong annotations, 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?

One concise sentence that front-loads the verb and resource, then adds the key behavioral detail about zero-to-many windows. No wasted words, and the structure is easy to parse.

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 tool with one optional parameter and no output schema, the description is nearly complete. It covers what the tool returns and the annotations cover safety. The only minor gap is that it doesn't mention the sibling setter or any default behavior when farm_id is omitted, but the schema already notes the default.

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 single parameter farm_id is fully documented in the schema. The description doesn't add any parameter-specific meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a read operation for producer-configured species gestation/age intervals and planned birth windows. It uses a specific verb ('Read') and names the resource ('birth history settings'), which distinguishes it from sibling tools like get_birth_event or get_birth_source_evidence. However, it doesn't explicitly contrast with its sibling set_birth_history_settings, 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?

The description implies this is a read-only retrieval tool, and the annotations confirm it. It doesn't explicitly state when to use this tool versus alternatives like set_birth_history_settings or get_birth_event. The context is clear enough for an agent to infer it's for fetching settings, but there's no explicit when/when-not 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, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it requires the source author's current farm access, partial/ambiguous matches require producer selection, and it explicitly states this lookup does not approve identities or save a birth. This clarifies side-effect boundaries and access requirements.

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

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

Three sentences with no waste. The core action and resource are front-loaded, followed by access requirements and explicit non-effects. 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 read-only lookup with two parameters and no output schema, the description covers the access requirement, the ambiguity handling, and the non-effects. It doesn't describe return values, but with no output schema and a read-only annotation, the description is reasonably complete. A small gap is not explaining what 'current-farm identity candidates' means or how producer selection is performed.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. The description mentions 'source author's current farm access' and 'producer selection', which hints at the farm_id parameter's role, but it doesn't explicitly explain source_sms_id or farm_id formats or semantics beyond the schema's uuid format. Baseline 3 is appropriate because the description adds some context but doesn't fully compensate for the 0% schema 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 ('Read') and resource ('retained SMS birth source, ordered media status, and current-farm identity candidates'), which clearly distinguishes it from sibling tools like get_birth_history_evidence or confirm_birth_event. It doesn't explicitly name a sibling, but the resource and scope are specific enough to differentiate.

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

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

The description gives clear context: it requires the source author's current farm access, and it notes that partial/ambiguous matches require producer selection. It doesn't explicitly say when to use this vs alternatives, but the 'requires' and 'does not approve identities or save a birth' exclusions provide practical usage boundaries.

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 readOnlyHint=true annotation already marks this as a safe read operation. The description adds behavioral context by specifying the return payload includes the widget config and processed animal entries, which is useful for an agent deciding whether this tool satisfies an information request. No contradiction with annotations.

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

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

The entire description is a single, front-loaded sentence that states the action and the key return contents with 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 lookup with two params and no output schema, the description is complete: it identifies the lookup key, the resource type, and what data is returned. The required parameter is self-evident from the schema, and the read-only behavior is covered by annotations.

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

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

Schema description coverage is 100%, with both parameters (farm_id and session_id) documented in the schema. The description adds no additional parameter semantics beyond contextualizing session_id as a UUID, but the schema already provides the necessary meaning.

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

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

The description states a specific verb ('Get') and resource ('single chute session by its UUID'), and specifies the returned content ('widget config' and 'animals processed'). It clearly differentiates from sibling tools like list_chute_sessions, which retrieve multiple sessions, by emphasizing 'single' and UUID-based lookup.

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 usage context: when you have a chute session UUID and need that specific session's details. However, it does not explicitly mention alternatives such as list_chute_sessions for enumeration or update_chute_session for modifications, nor any when-not-to-use 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?

With no annotations, the description carries the full burden; 'Get' clearly signals a read operation with no destructive intent, and the mention of 'including default farm ID' hints at the returned data. It does not disclose other behavioral details such as auth requirements or what else 'current context' contains, but for a zero-parameter getter the core safety profile is apparent.

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 filler. Every word contributes to identifying what the tool does.

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, no-output-schema tool, the description is mostly adequate but leaves 'current context' undefined and does not enumerate the return fields besides default farm ID. An agent can call it correctly, but may not know precisely what to expect in the response.

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

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

The input schema has no parameters, so there is nothing for the description to add; the baseline of 4 applies. The description's mention of default farm ID gives a hint about output rather than input.

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

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

The description uses a specific verb ('Get') and a distinct resource ('current context'), and even names one contained field ('default farm ID'). It does not explicitly distinguish from sibling tools like get_farm or list_my_farms, but the scope is clear.

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

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

The description implies this is the tool for reading the active context and default farm ID, but it does not state when to prefer it over get_farm, list_my_farms, or set_default_farm. No exclusions or alternative 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?

With no annotations, the description carries the transparency burden. 'Get details' sufficiently signals a read-only retrieval operation, but it does not describe error behavior (e.g., not-found), response shape, or any permissions required, leaving some behavior implied rather than explicit.

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

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

One short, front-loaded sentence with no filler. It states exactly what the tool does and is easy to scan.

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 retrieval with a fully documented schema, the description plus schema provides enough to invoke the tool correctly. It lacks detail about return contents and error cases, but complexity is low and no output schema exists, so this 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?

The schema already documents farm_id with 100% coverage, so the baseline is 3. The description adds no new information about the parameter beyond 'specific farm,' which loosely references the ID but doesn't explain format, constraints, or source.

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

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

Description states a clear verb ('Get') and resource ('a specific farm'), indicating this tool retrieves one farm rather than listing or modifying. It is slightly generic and doesn't differentiate from sibling get_* tools, but the 'specific farm' phrasing clearly distinguishes it from list_my_farms.

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 'a specific farm' implies this tool is for retrieving a single farm when its ID is known, but the description does not explicitly mention when not to use it or point to alternatives such as list_my_farms for listing multiple farms.

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=true, so the safe-read nature is covered. The description adds useful return-content context (snapshot and deliveries) but does not disclose additional behavioral details such as not-found handling, authentication needs, or response format. It does not contradict the readOnlyHint.

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-structured sentence that front-loads the action and resource, then adds the important return details. There is no filler or repeated information already present 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?

With no output schema, the description wisely explains what the response will contain (ingredient snapshot and per-group deliveries). It is adequate for a simple read-only getter; the only minor gap is the lack of error or not-found behavior, which is not critical for tool 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 description coverage is 100%, so the schema already documents both feeding_id and farm_id. The description reinforces that lookup is by UUID but adds no extra semantic detail beyond the schema, such as how the optional farm_id default behaves.

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

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

The description clearly states the action ('Get a single feeding by its UUID') and specifies the exact scope, distinguishing it from list_feedings. It also names the contained data (ingredient snapshot with targets/actuals and per-group deliveries), which removes ambiguity about what this tool returns.

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 'Get a single feeding by its UUID' implies use when a caller needs one specific feeding record, not a list or a chute session. However, it does not explicitly state when to prefer another tool or exclude alternatives, so the guidance is clear but not fully explicit.

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

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

Annotations include readOnlyHint=true, so the description doesn't need to explain safety. The description adds that it includes members, which is useful beyond the schema. However, it does not disclose potential errors (e.g., group not found) or default farm behavior, which could be relevant. Since annotations cover the read-only aspect, a 3 is fair.

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 sentence that front-loads the core function and includes a useful detail about members. No 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 simple read tool with full schema coverage and readOnlyHint annotation, the description covers the essential purpose. It doesn't explain the return format, but no output schema exists and the tool is straightforward. A minor gap is not specifying behavior when group is missing, but overall sufficient.

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 parameters are fully described in the schema. The description does not add extra meaning beyond what the schema already provides (group_id and farm_id are self-explanatory). 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 clearly states the tool fetches a single group by UUID and includes members. It is a specific verb+resource, and the sibling list has related tools like list_groups and get_group, but the description distinguishes it as single vs list. However, it doesn't explicitly mention the alternative for listing all groups, which would make it 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 implies when to use it (when you need a single group's details) but does not explicitly state when not to use it or mention alternatives like list_groups. The context of siblings provides a hint, but the description itself lacks explicit routing guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly discloses that URLs expire in 1 hour (time-limited), and warns that file contents are untrusted and instructions inside them should never be followed (security note). This is rich, beyond what the schema or annotations would convey.

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

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

The description is concise, with two sentences: the first states the primary function and access level, and the second provides a critical security warning. It is front-loaded with the most important information, and there is no 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 tool with a single parameter and no output schema, the description covers essential aspects: what it does, the access level, the nature of the URLs (presigned, expiring), and a safety warning. The only minor gap is that it doesn't explicitly explain the return format (e.g., a JSON structure), but given the simple nature, this is sufficient.

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

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

The schema covers 100% of the parameter (import_request_id) with a description that is generic but adequate. The tool description does not add extra meaning about the parameter beyond the schema. With high schema coverage, 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 uses a specific verb 'Get' and a specific resource 'import request', and clearly states the key behavior: it returns presigned download URLs for the request's files. This distinguishes it from sibling tools like list_pending_imports and update_import_request_status.

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 implicitly indicates usage by stating 'admin only', which sets a clear access prerequisite. However, it does not explicitly explain when to use this tool versus alternatives, or when not to use it. But the context of retrieving a single request with its files is clear enough for the agent.

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, and the description adds behavioral context by noting that the returned ration includes its ingredients in load order and group assignments. This goes beyond the annotation and helps set expectations about response structure.

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, efficient sentence. It front-loads the core operation (get a single ration by UUID) and then adds the most valuable response details without any wasted 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?

Given the simple get-by-UUID operation, the schema fully documents parameters, and annotations cover the read-only nature, the description provides the key missing context: what the response will include. No critical information is absent for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already well documented in the schema. The description adds no additional parameter-level detail, so a baseline score of 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 clearly states the action ('Get a single feed ration'), the resource ('a feed ration'), and the key identifier ('by its UUID'). It also specifies what the response includes, distinguishing it from list_rations which would return multiple rations.

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 clearly implies when to use this tool: when you need one specific ration by UUID. It does not explicitly mention alternatives like list_rations for fetching multiple rations, but the singular scope and UUID requirement provide clear context.

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

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

Annotations already declare readOnlyHint=true, so the read-only behavior is known. The description adds value by disclosing that the response includes affected animals/groups, giving the agent useful information about the returned data beyond a bare 'get' operation.

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

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

A single sentence with no filler. The primary action and target are front-loaded, and the additional detail about affected animals/groups is concise and useful.

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

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

For a simple read-only retrieval tool, the description plus schema and annotations cover what an agent needs to invoke it correctly. The lack of an output schema is partly mitigated by the mention of affected animals/groups, though the exact response shape is not detailed.

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 (farm_id and record_id) are fully documented in the schema. The description does not add parameter-specific meaning beyond mentioning UUID, which aligns with record_id, but it does not enrich farm_id semantics.

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

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

The description clearly states a specific verb ('Get'), a specific resource ('a single record'), and the identifying key ('by its UUID'). It also signals additional context ('including affected animals/groups'), which helps distinguish it from list-oriented siblings like list_records.

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

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

The description implies this is for fetching a single record by UUID rather than listing records, but it does not explicitly contrast with list_records or mention when not to use it. No alternative tools or exclusion conditions are stated, so usage guidance is only implicit.

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

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

Annotations already mark it read-only, so the safety profile is known. The description adds behavioral nuance: default results are current animals, and ALL reveals historical/nondeleted profiles, which is useful beyond the schema.

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

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

Two sentences, each earning its place; the core operation is named first, pagination second, and the status-selection behavior follows 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 list with four optional, fully documented parameters, the description covers purpose, pagination, and the status distinction. It omits explicit routing to alternatives, but the schema closes most remaining 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 coverage is 100%, so the schema carries the technical definitions. The description enriches the inventory_status parameter by framing CURRENT as 'current' and ALL as 'historical profiles,' which clarifies the enum's purpose.

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?

Clearly identifies the operation and resource: listing animals on the farm. The 'current' vs historical distinction via inventory status separates it from generic list 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?

Implies this tool is for current farm animals and can be pointed at historical profiles via ALL, but it names no alternatives or explicit when-not-to-use. An agent must infer that list_groups/list_records are the siblings to choose instead.

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

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

The description is consistent with annotations (readOnly, idempotent, non-destructive). It adds behavioral detail about bounded pagination and optional filtering by dam or offspring, which is beyond annotations. However, it does not elaborate on response format or ordering, though annotations already cover safety.

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

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

One sentence, front-loaded with the core purpose, and no filler. It efficiently communicates what, how (pagination), and optional filters.

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

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

For a simple list tool with read-only annotations and explicit pagination defaults in the schema, the description covers the essential usage. It lacks details on return shape and ordering, but given the simplicity and existing annotations, it is sufficiently 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 coverage is 0%, so the description must compensate. It mentions pagination (bounded) and filtering by dam or offspring, which maps to skip/take and animal_id, but it does not explicitly map farm_id or clarify which parameter corresponds to dam vs offspring. Parameter names themselves are self-explanatory (farm_id, animal_id), so the description adds moderate value.

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

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

The description uses a specific verb ('List') and resource ('saved birth events'), and distinguishes itself from siblings like get_birth_event (single event) and preview_birth_event (preview). Mentioning saved events implies it lists already confirmed/recorded events, which separates it from preview/confirm 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?

The description implies when to use the tool (to list saved birth events) but does not explicitly contrast it with alternatives like get_birth_event or list_farm_tasks. The usage is clear from the purpose, but there is no explicit when-not or alternate routing.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds the status semantics (e.g., PROPOSED means assistant-built awaiting confirmation), which is valuable context beyond the schema. However, it doesn't describe pagination behavior or default ordering, though these are partially implied by skip/take parameters.

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 two sentences with minimal waste. The first sentence states the core purpose and context; the second sentence explains the filter option with enum meanings. It's front-loaded and every word carries 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?

Given the tool's moderate complexity (4 optional params, no output schema) and the annotations covering safety, the description is fairly complete. It explains the status filter semantics, which is the main behavior. Missing details like pagination defaults or sort order are minor for a list operation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the meaning of each status enum value (PROPOSED, ACTIVE, COMPLETED), which is not in the schema. This is a baseline 3, with slight improvement from the enum clarification.

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

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

The description clearly states the verb (list) and resource (chute-mode work sessions), adds context (chute-side capture runs: weigh days, preg checks, vaccinations), and differentiates from siblings by naming the specific session type. It fully distinguishes from list_groups, list_records, and get_chute_session without ambiguity.

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

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

The description provides clear context for when to use the tool (listing chute sessions) and explains the optional status filter with specific meanings (PROPOSED, ACTIVE, COMPLETED). It doesn't explicitly name alternative tools for similar lists, but the context is sufficient and the filter explanation is helpful.

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 and idempotentHint=true, so the safety profile is clear. The description adds one useful behavioral detail—'including undated todos'—that explains the listing scope beyond annotations, but does not cover pagination behavior, filtering defaults, or how status interacts with the listing.

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?

Single sentence, front-loaded with the action and resource, and no filler. It conveys exactly enough to understand the tool's core purpose.

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

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

For a list endpoint with four optional parameters and no output schema, the description is thin. It does not explain what happens when farm_id is omitted (likely uses current context), the meaning of status values, or whether the result includes tasks across all farms or only the current one. An agent may need to probe the API to understand the default 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?

The schema properties (skip, take, status, farm_id) are well-defined by names, types, and enums, but schema description coverage is 0% and the description adds no information about these parameters. Since description coverage is low and there are 4 params, the description fails to compensate, leaving semantics like pagination and filtering to inference.

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

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

The description uses a specific verb (List) and resource (farm follow-up work/farm tasks), and notably includes 'including undated todos,' which clarifies the scope. This clearly distinguishes it from sibling list tools like list_groups, list_rations, and list_record.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention the optional farm_id fallback to current context, filter semantics, or cases where one might prefer list_records over this tool. Usage is only implied by the name and 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 declare readOnlyHint=true, so the description doesn't need to state safety. It adds useful context about the returned fields (ration, status, batch scale factor, total pounds) and ordering (newest first), which goes beyond the bare schema. However, it doesn't disclose potential pagination behavior (like maximum page size) or that it might require a farm context, but given the read-only annotation and that the schema already has pagination parameters, 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?

The description is a single, clear sentence that front-loads the main purpose and includes key details (ordering, fields) without excessive fluff. It's efficient and to the point, but could arguably add a mention of filtering options for completeness, which would be a minor improvement. Overall it's well-structured and concise.

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 list tool with a read-only annotation and a schema that covers all parameters, the description is largely complete: it tells what the tool does, the ordering, and the returned fields. It doesn't describe the output format (e.g., JSON array of objects), but no output schema exists and the schema is simple (flat, no nested objects). The lack of explicit alternative guidance (e.g., get_feeding) is a minor gap, so 4 is appropriate.

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 five parameters are already described in the schema (skip, take, since, status, farm_id). The description adds minimal parameter-level meaning beyond what the schema provides—it only mentions the returned fields, not parameter specifics. Since coverage is high, a baseline of 3 is justified, and the description doesn't need to compensate.

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

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

The description clearly states it lists feedings (executed mixer loads) on the farm, with a clear verb and resource, and includes the ordering (newest first) and the key fields displayed. It distinguishes itself from related tools like get_feeding (singular) by implying a list operation, and the parenthetical clarifies what a feeding is. It is specific and not a tautology.

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 usage (listing feedings) but does not explicitly state when to choose this tool over alternatives like get_feeding, nor does it mention any exclusions or conditions. No reference to filtering or pagination options, though the schema provides those. Contextual signals like sibling names don't provide explicit guidance, so it relies on the user to infer this is the list counterpart to get_feeding.

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 provide readOnlyHint=true, and the description does not contradict this. The description adds the resource scope but discloses no additional behavioral traits such as pagination, ordering, default-farm handling, or response shape. With the read-only annotation covering the safety profile, this is adequate but minimal.

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 or redundancy. Every word earns its place, and it is appropriately sized for a simple list 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 low-complexity read-only list tool, the description, combined with the annotated optional schema and readOnlyHint, is largely sufficient. It does not explain return values or default-farm behavior, but the schema covers the parameter and the annotation covers the safety aspect, leaving only minor contextual 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 farm_id is already documented. The description's 'on the farm' only loosely echoes the parameter and adds no deeper meaning about how farm_id behaves, such as the optionality or default-farm fallback.

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 ('List') and resource ('animal groups'), making it immediately clear this is a collection-level read operation. It also distinguishes from sibling tools like get_group, create_group, update_group, delete_group, and restore_group, and from other list_* tools that target different resources.

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 usage context is implied: use this to enumerate groups rather than to fetch or mutate a single group. However, there is no explicit when-to-use guidance or mention of alternatives such as get_group for retrieving group details, so the guidance is not directly stated.

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, so the read-only nature is covered. The description adds the specific identifier categories returned, which gives some sense of output content, but it does not disclose behaviors such as pagination, ordering, handling of missing animals, or whether only current or historical identifiers are shown. This is adequate but not rich.

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, tightly written sentence that leads with the action 'List' and immediately specifies the resource. The parenthetical list of identifier types is informative without adding bulk. There is no wasted words or redundant content.

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

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

The tool is simple (two parameters, read-only, no output schema), and the description covers the core action. However, it does not state the return format or any special edge-case behavior. Given the lack of an output schema, the description could have briefly mentioned that a list of identifiers is returned. It is functional but not fully self-sufficient.

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

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

With 100% schema description coverage, the schema already documents both animal_id and farm_id. The description's phrase 'for a given animal' implicitly references animal_id but adds no new meaning beyond the schema. The baseline of 3 applies because the schema does the heavy lifting and the description does not contradict or augment it.

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 ('List'), a clear resource ('identifiers'), and scope ('for a given animal'), while enumerating the identifier types (tags, names, EID, brand, tattoo). This differentiates it from sibling tools like add_identifier, remove_identifier, and find_animal_by_identifier, making the purpose instantly clear.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention that this is the tool to retrieve identifiers for a known animal, nor does it contrast with find_animal_by_identifier (which searches by identifier) or list_animals (which lists all animals). An agent must infer usage from the verb and resource.

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, so the safety profile is covered. The description adds that it returns current values per key and is meant for pre-save checks, which is useful behavioral context. However, it doesn't disclose details like whether the list is sorted, paginated, or limited to a single farm scope beyond the farm_id 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 sentences with no filler. The core purpose is front-loaded, and the usage guidance is a natural second sentence. 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 one optional parameter and no output schema, the description covers purpose, usage timing, and scope. It could mention what happens when no farm_id is provided (e.g., uses default farm), but the schema already notes the default, so the description is nearly complete.

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

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

Schema description coverage is 100% (farm_id is described as optional if a default is set), so the schema already documents the parameter. The description adds the context that the list is farm-scoped, but doesn't add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('what the assistant currently remembers about this farm'), and clarifies it returns the current value per key. It distinguishes itself from sibling tools like list_records and list_groups by focusing on assistant memory, not farm data records.

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

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

The description explicitly says to use it 'before saving a memory to avoid duplicate or conflicting keys,' giving a clear when-to-use directive. It also implies the alternative context (saving/updating memories) without needing to name a sibling, which is sufficient given the sibling list contains update_record and delete_record.

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 are not provided, so the description carries the full burden of behavioral disclosure. The description only states the action and scope but does not disclose behaviors such as whether the list includes archived farms, pagination limits, ordering, or performance implications. There is no mention of any side effects or prerequisites. For a read operation, more context is needed given no annotations to fall back on.

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, concise sentence that states the verb, resource, and scope clearly. It is front-loaded with the core purpose and contains no fluff or irrelevance. Every word is necessary, and it is appropriately sized for a tool with no parameters or complex behavior.

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

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

For a simple list operation with no parameters and no output schema, the description is minimally complete: it tells the agent that the tool lists farms, which is sufficient to invoke it. However, it lacks information on what the output contains (e.g., farm IDs, names) and any filtering or pagination behavior, which could be important for agent decisions. Given the simplicity, it is adequate but not rich; a higher score would require more operational details.

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 are zero parameters, and the schema has full coverage (100%) in the sense that the schema is empty but complete. With no parameters to explain, the description does not need to add parameter semantics. The description correctly implies no inputs are required, so a baseline of 4 is appropriate (as per guidelines for 0 params).

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

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

The description 'List all farms that the user has access to' clearly states the action (list) and resource (farms), and specifies the scope (farms the user has access to). This distinguishes it from similar list tools like list_groups or list_animals, though it could name a sibling explicitly. Sibling differentiation is implicit through the resource type, so it is clear but not maximally explicit.

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 when to use this tool: when you need to list farms the user has access to, which is useful for context or selection. However, it does not explicitly state when not to use it or mention alternatives like get_farm or set_default_farm. It provides minimal guidance, leaving some inference to the agent, which is adequate but not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the admin-only restriction and the default status, which is useful, but it does not disclose pagination behavior, ordering, whether results are limited, or what happens when no status is provided. For a list tool, the lack of any note about result size or filtering behavior is a notable gap.

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 sentence that front-loads the core action and resource, then adds the admin-only qualifier and default status. It is concise and every phrase earns its place, though it could have added a brief note about pagination without much cost.

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

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

For a simple list tool with three optional parameters and no output schema, the description is mostly complete. However, it lacks any mention of pagination behavior or result ordering, and the admin-only restriction is the only contextual note. Given the absence of annotations and output schema, a bit more context about what the response contains or how pagination works would make it fully 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 three parameters (skip, take, status). The description adds the default status value ('PENDING') which reinforces the schema, but it does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a clear resource ('concierge import requests'), and a scope ('across all farms'), with an admin-only qualifier. It does not explicitly distinguish it from sibling tools like get_import_request or update_import_request_status, but the plural 'list' and status default make the purpose reasonably clear.

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

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

The description implies usage by naming the resource and default status, and the admin-only note gives a prerequisite. However, it does not explicitly say when to use this tool versus alternatives like get_import_request, nor does it mention that status is optional and defaults to PENDING beyond the schema. The guidance is adequate but not explicit.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds meaningful context by declaring definitions 'immutable' and pagination 'bounded'. The instruction 'Never invent missing steps' also communicates an important behavioral constraint beyond the annotations.

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

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

The description is short and front-loaded with the core operation. The second sentence 'Never invent missing steps' is terse and somewhat ambiguous, so not every part is maximally clear, but the overall structure is compact.

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

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

The core listing behavior and safety profile are clear from the annotations and description. However, the role of farm_id and the exact pagination semantics beyond being 'bounded' are left to inference, and there is no output schema to clarify the return shape.

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

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

Schema description coverage is 0%, and the description only hints at pagination without explaining skip, take, or farm_id. It does not compensate for the schema's bare property names or clarify what farm_id filters.

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

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

The description clearly states the action 'List', the resource 'immutable farm protocol definitions', and a notable scoping property 'bounded pagination'. This distinguishes it from the many sibling list_* tools by naming a specific resource 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?

The description implies it is used to enumerate protocol definitions, and the resource name is clear. However, it gives no explicit guidance on when to prefer this tool over alternatives such as create_protocol_version or other list tools, and it does not mention 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 mark it read-only, and no annotation contradiction exists. The description adds useful scope ('on the farm') and content expectations (ingredients, group assignments), but it does not disclose additional behavioral traits like default active-only filtering or pagination behavior beyond what the schema parameters imply.

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: it names the operation, the scope, and the content of the returned items. Every clause adds value.

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 no output schema and all-optional parameters, the description supplies the essential mental model: what a ration is and what the list will contain. The schema covers pagination and active/inactive controls, 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?

Input schema coverage is 100% with individual property descriptions, so the schema already carries parameter meaning. The description adds no parameter-level semantics (e.g., how skip/take or include_inactive work), which is acceptable at 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 and resource ('List feed rations') and enriches it with a precise definition: named recipes in per-head-per-day amounts with ingredients and group assignments. This clearly differentiates it from siblings like list_feedings, get_ration, and list_groups.

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 the tool is for farm-level ration definitions rather than actual feeding events, but it does not explicitly compare with alternatives such as get_ration or list_feedings, nor does it state when not to use it. Context is present; exclusions and alternate routing are absent.

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 annotation readOnlyHint: true already covers the safety profile, so the bar is lower. The description adds context about what records are (events) but does not disclose behavioral details like pagination behavior, ordering, or that only records from the current farm are returned. Since it adds some context beyond the annotation, a 3 is fair.

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 sentence that front-loads the core action ('List records') and then adds clarifying context. No wasted words, perfectly concise and 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?

The tool is simple and all parameters are documented in the schema, but the description lacks usage guidance (e.g., when to prefer this over list_groups) and does not mention output format or pagination defaults. Since there is no output schema and many siblings, more context would be helpful, but the core purpose is covered. A 3 reflects the moderate completeness.

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

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

Schema coverage is 100% with each parameter having a description. The tool description adds no additional meaning to the parameters; it doesn't elaborate on skip/take semantics or the type filter. Given the high schema coverage, 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 clearly states the action (List) and resource (records), and provides helpful examples of what records are (events applied to animals or groups). It does not explicitly differentiate from sibling tools like list_groups or get_record, but the resource is distinct enough. A clear verb+resource with context, so 4 is appropriate.

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?

No guidance on when to use this tool versus alternatives. It does not mention that get_record is for a single record, or that create_record/update_record/delete_record are for mutations. The description only states the purpose, not the selection criteria. This is a gap.

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 established. The description adds meaningful behavioral context: it validates without saving, resolves dam/group/protocol/evidence details, requires explicit approval, and mandates a fresh preview after corrections.

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

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

Three dense sentences with no fluff. The most important constraints—non-saving preview and approval before confirmation—are front-loaded, and every sentence earns its place.

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

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

For a preview tool with read-only annotations and no output schema, the description fully covers the agent's needs: what the tool does, what it shows, when to call it, and what to do before calling the confirmation sibling. The nested schema provides field-level detail where needed.

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

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

Schema description coverage is only 33%, and the description adds almost no parameter-specific meaning beyond referring generically to 'every bundle field.' It does not mention request_id preservation, farm_id, or clarify which bundle fields matter, so it fails to compensate for the low schema 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 opens with a specific verb-resource pair, 'Validate and preview one atomic birth event,' and immediately clarifies it is a non-saving preview. It also distinguishes itself from the sibling confirm_birth_event by framing this tool as the approval-gathering step before confirmation.

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

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

The description explicitly states when this tool should be used: before calling confirm_birth_event, and only after obtaining explicit producer approval of the exact preview. It also states the retry behavior, 'Any correction requires another preview,' which gives clear procedural 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not disclose whether this action is destructive (removing an identifier might be irreversible), whether it requires specific permissions, or whether it has side effects on related data. The description only says 'remove', which implies mutation but adds no detail about consequences, reversibility, or logical deletion vs hard deletion.

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, concise sentence that is front-loaded with the primary action and target. There is no fluff or repetition. Every word earns its place, making it highly efficient.

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

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

Given that this is a mutation tool with no annotationshare, the description is incomplete. It does not mention any output or response, which is not critical since there is no output schema, but more importantly, it lacks information about error conditions, required permissions, or what happens after removal. The tool has 3 parameters including a required animal_id and identifier_id, and the description barely explains the operation. For a tool that could be destructive, the description should provide more context on usage and consequences.

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

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

The input schema has 100% coverage: each parameter has a description, including 'farm_id' which notes it is optional if default is set. The description itself does not add any parameter-specific details beyond the schema, but since the schema already documents each parameter clearly, the description does not need to compensate. The description adds nothing about parameter relationships or validation requirements, but the schema is sufficient.

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 ('remove') and resource ('identifier') and clarifies that it applies to an animal. This clearly distinguishes it from sibling tools like 'add_identifier' and 'delete_record', though it could be more explicit about the context (e.g., removing an identifier from an animal's record). The phrase 'from an animal' provides enough context to understand the operation.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention that 'add_identifier' is the opposite operation, nor does it specify any prerequisites (e.g., the animal must exist). There is no context on when it is appropriate to remove an identifier versus updating or deleting it. The sibling tools include both 'add_identifier' and 'update_record', but no exclusions or 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?

Annotations already indicate the operation is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that the group is 'previously archived' and will be returned to the 'active list,' which gives context on the state transition. However, it does not disclose potential side effects, permission requirements, or behavior when the group is already active or not found. With annotations covering the basic safety profile, the description adds some value but not rich behavioral detail.

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 sentence with zero waste. It front-loads the action ('Restore') and the object ('previously archived group') before the outcome. Every word contributes to the meaning, making it highly efficient and easy to parse.

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 only two parameters and no output schema, the description is mostly adequate. It explains the core function and state change. However, it does not mention preconditions (e.g., the group must be archived), potential failure modes (e.g., invalid group_id), or what the response will look like. Given the absence of an output schema and the minimal annotations, a slightly richer description would improve completeness, so a 3 is justified.

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

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

Schema coverage is 100%, and both parameters have clear descriptions in the schema. The description itself adds no additional parameter details beyond what the schema provides. Per the baseline rule for high schema coverage, a score of 3 is appropriate since the schema carries the full burden of parameter documentation.

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

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

The description uses a specific verb ('Restore'), a specific resource ('previously archived group'), and a clear outcome ('back to the active list'). This clearly distinguishes it from sibling tools like create_group, delete_group, or update_group, as it explicitly targets archived groups. The purpose is unambiguous and immediately actionable.

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 when to use the tool (when a group is archived and needs reactivation) but does not explicitly state alternatives or exclusions. It does not name sibling tools like list_groups or create_group as alternatives, nor does it mention when NOT to use this tool (e.g., if the group is not archived). Context is clear but not exhaustive, so it earns a mid-range score.

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 say idempotentHint=true, and the description's 'Replace' implies a full overwrite, which is consistent. The description adds a critical behavioral rule: never invent biological interval defaults; empty array means no planned windows. This goes beyond annotations to warn about a common mistake, making it strong.

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-to-two sentences, front-loads the core action, and delivers a precise caveat. No fluff or repetition of schema details. 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?

The tool is moderately complex with nested objects, but the schema covers most parameter details. The description explains the critical edge case (empty array), and annotations cover idempotency and safety. It doesn't mention error conditions or response behavior, but given no output schema, that 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?

Schema coverage is only 50%, and most parameters like farm_id, species, version, gestation_days, minimum_sire_age_days are self-explanatory from the schema, but the description clarifies the crucial birth_windows parameter's behavior (empty = no planned windows). This compensates for the coverage gap, especially for the nested structure.

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 it replaces explicit producer-approved birth-history settings. The verb 'Replace' and resource 'birth-history settings' are specific, but it does not distinguish from its sibling get_birth_history_settings beyond implying a setter. The description also clarifies the semantics of an empty array, which adds specificity.

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?

Implies usage by indicating it should only be used with explicit producer-approved settings, and warns against inventing defaults. It does not explicitly say when not to use it or mention alternatives like get_birth_history_settings, so guidance is present but incomplete.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states that a default is set for subsequent operations, but does not mention persistence, overwriting an existing default, permissions required, or side effects beyond the operation itself.

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, direct sentence with no filler. It front-loads the action and clearly states the effect on subsequent operations.

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

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

For a one-parameter tool with no output schema, the description is minimally adequate. However, it leaves gaps around how the default is applied, whether it replaces an existing default, and what contexts or operations consume it, which an agent would benefit from knowing.

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

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

The schema already fully describes farm_id as 'The ID of the farm to set as default' with 100% coverage. The description adds little beyond the schema, so the baseline of 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 uses a specific verb ('set') with a specific resource ('default farm ID') and explains the purpose ('for subsequent operations'). It clearly distinguishes this tool from sibling list/get tools and conveys its state-changing role.

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 'for subsequent operations' implies when the tool should be used, but it does not explicitly state prerequisites, exclusions, or alternatives such as retrieving the current default via get_current_context. Usage context is implied rather than explicitly guided.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the key merge behavior: provided fields merge into existing metadata rather than replacing it, so unrelated fields are preserved. This is a valuable non-obvious behavioral trait not inferable from annotations 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 sentences with the core action front-loaded and the merge rule stated clearly. The parenthetical list of fields is redundant with the schema but not overly verbose; the description remains efficient and readable.

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

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

For an update tool with 11 parameters and one required, the description covers what can be changed and the merge semantics. It does not describe the return value (no output schema exists), but this is a minor gap for a mutating tool whose safety profile is already annotated.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the field list already present in the schema and restates the merge behavior also described in the metadata parameter. It adds minimal semantic value 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?

The description states a specific action ('Update an existing animal's details') with a clear resource (animal) and lists the updatable fields. It does not explicitly differentiate from sibling update tools like update_record or update_chute_session, but the resource is unambiguous from name and description.

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 when to use the tool (to modify animal details) but provides no guidance on when not to use it or which alternative to prefer (e.g., delete_animal, create_animal, or update_record). No exclusions or alternative routing 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?

It discloses an important behavioral trait: the widget grid is a full replacement list, not an incremental edit. It also clarifies the state constraint that only PROPOSED sessions are editable, which goes beyond the minimal readOnlyHint=false and destructiveHint=false annotations. This gives the agent meaningful behavior information for invoking the tool safely.

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 two sentences with no wasted words. It front-loads the action and state constraint, then adds the crucial replacement semantics and exclusion. Every clause contributes useful 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 6-parameter mutation with no output schema, the description covers the core operation, the session-state restriction, and the full-replacement semantics. It could be slightly more explicit about what happens when optional fields like group_name or record_type are provided, but the schema covers those parameters, so 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?

Schema description coverage is 83%, so the baseline is 3. The description adds value by mapping the tool's purpose to the name and widgets parameters ('rename it or replace its widget grid') and pointing to create_chute_session for widget types and arrangement rules. It doesn't elaborate on farm_id, group_name, or record_type, but the schema already documents those.

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 precise action and resource: 'Revise a PROPOSED chute session before the user starts it,' with concrete operations (rename or replace the widget grid). It also contrasts with create_chute_session by referencing the same widget rules, making it easy to distinguish from creation/list/get 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 explicitly says when to use the tool: before the user starts the session. It also explicitly says when not to use it: started sessions cannot be changed here, and only the operator can edit those in the app. This provides clear routing guidance relative to create_chute_session and app-side editing.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false∵. The description adds meaningful behavioral detail: the special semantics for due_date (null clears, omission preserves). It does not contradict annotations; in fact, it aligns with idempotency. However, it does not disclose other behavioral traits like authorization requirements or side effects beyond the status change, so it adds only moderate value.

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 one sentence of moderate length, front-loading the main purpose ('After producer approval, update task status') and then adding the critical due_date nuance. It is efficient with words, but the phrasing 'An explicit null clears the date; omission preserves it' is slightly dense; however, it earns its place. No wasted words, but it could be split into two sentences for readability.

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

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

The tool has 4 parameters, with 2 required, and no output schema. The description covers the key state-changing aspects (status and due_date) and the approval precondition. However, it does not explain what happens to other fields like farm_id, or whether status change is final, nor does it provide any return-value information. Given the moderate complexity and no output schema, the description is adequate but could be more 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 0%, meaning the schema provides no descriptions for parameters. The description explains the behavior of due_date (null clears, omission preserves), which adds crucial meaning beyond the schema's type and pattern. It does not explain status enum values, but those are self-explanatory (TODO, DONE, CANCELLED). Given the lack of schema descriptions, the description compensates well for the key ambiguous 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?

The description clearly states the verb (update) and resource (farm task), and specifies that it updates task status and optionally the due date after producer approval. It does not explicitly differentiate from siblings, but the use of 'farm_task' in the name and reference to producer approval provides decent distinction from general update tools like update_record.

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 'After producer approval' implies a precondition for usage, giving context about when this tool is appropriate. It does not explicitly mention alternatives or when not to use it, but the conditional context is clear enough for an agent to infer it should be used only after approval. A stronger definition would name the alternative (e.g., create_farm_task) and explicitly state when not to use it.

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 agent knows this is a mutation but not destructive. The description adds no behavioral context beyond 'update' – it doesn't say whether partial updates are supported, whether all fields are overwritten, or what happens if the group doesn't exist. With annotations covering the safety profile, a 3 is fair: the description adds minimal value but doesn't contradict anything.

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 short sentence with no waste. It's front-loaded and efficient. It could add a bit more context, but for what it is, it's concise and structured well.

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 update tool with full schema coverage and annotations, the description is minimally sufficient. It doesn't explain return values (no output schema), but that's not required. It could mention whether the update is partial or full replacement, which is a common ambiguity for update tools. Given the simplicity, a 3 is appropriate – adequate but with a clear gap around update semantics.

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 four parameters. The description adds no additional meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description 'Update an existing group' clearly states the verb (update) and resource (group), and the schema confirms group_id is the target. It doesn't explicitly distinguish from sibling tools like update_record or update_farm_task, but the resource name is specific enough that an agent can infer the target. A 4 is appropriate because it's clear but lacks explicit 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?

The description implies usage: call this when you need to modify an existing group. It doesn't state when not to use it or mention alternatives like create_group or delete_group. The context is clear from the resource name, but there's no explicit guidance on prerequisites (e.g., group must exist) or when to prefer other tools. This is adequate but with gaps.

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

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

No annotations are provided, so the description carries the full burden. It mentions 'admin only' which is useful, but it does not disclose important behavioral details such as whether the update is idempotent, whether any side effects occur (e.g., triggering notifications), whether failed transitions are allowed, or what the response looks like. The tool mutates state, so without more context on effects and the rejection of invalid transitions, it is under-specified.

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, concise sentence that front-loads the action, includes the valid statuses, notes the optional summary, and flags the admin-only restriction. Every part is informative, and there is no redundancy with 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?

Given that this is a state-changing operation with no annotations and no output schema, the description is too thin. It lacks details like the workflow around status transitions (e.g., can you move from COMPLETED back to PROCESSING?), the consequences of setting a status, and any special permissions beyond 'admin'. The presence of sibling tools like list_pending_imports suggests a business process, but the description does not explain how this tool fits into it.

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

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

The input schema already provides full documentation for all three parameters (with descriptions), so the description doesn't need to add much. The description mentions 'optional summary of what was loaded' which aligns with the 'summary' parameter, and the status enum is self-explanatory. The description adds no additional semantics beyond the schema, but given 100% coverage, the baseline of 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 clearly states the action ('Mark an import request') and specifies the three possible statuses (PROCESSING, COMPLETED, FAILED). It also includes that it can optionally add a summary, and marks it as admin-only. Although it doesn't explicitly differentiate from siblings like list_pending_imports or get_import_request, the action verb 'update' and the status values make its purpose distinct enough.

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

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

The description implies this is used to transition import requests to a final or processing state, and notes 'admin only' as an access requirement. It doesn't explicitly state when to use this versus other tools, but the statuses and the context of import workflows make the usage reasonably clear. As there are no direct sibling tools for updating imports, the lack of explicit comparisons is acceptable.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds little beyond confirming mutation. It does not disclose update semantics such as whether omitted fields are left unchanged, whether updates are full or partial, or what happens on missing/invalid record_id.

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 concise sentence with no filler, and the core action is front-loaded. However, it is so terse that it sacrifices useful detail, which slightly reduces the effectiveness of its brevity.

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 6 parameters, no output schema, and minimal annotations, this description is incomplete. It omits update behavior, response format, required fields beyond an implicit record_id, and any constraints such as enum values or date formats.

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

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

Schema description coverage is only 50%, and the tool description contributes no parameter-level meaning. It does not mention which fields are updatable, which are required, or how farm_id/applied_at/type relate to the update operation, so it fails to compensate for the schema's gaps.

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: 'Update an existing record.' It clearly signals modification of an existing entity rather than creation or deletion, though it does not explicitly name sibling tools or list the record fields involved.

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?

No guidance is given about when to use this tool versus create_record, delete_record, get_record, or list_records. The phrase 'existing record' weakly implies it should not be used for creation, but there is no explicit context, prerequisite, or alternative routing.

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