QuailOS

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

Annotations already declare the write/non-idempotent/non-destructive profile, and the description adds genuinely new behavioral facts: the SuperAdmin authorization requirement and the confirm:true gate before execution. It still omits what else activation touches (e.g., whether a payment record is created) and what happens on failure.

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 telegraphic fragments, front-loaded with the action and state transition before the authorization and confirmation constraints. Nothing is padded, though the fragmentary style is minimal rather than well-structured prose.

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 state-flip mutation with no output schema and only three flat parameters, the description covers the key constraints (admin-only, confirm). It is still thin on downstream effects of activation and says nothing about the two required ID parameters, which matters given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains the non-obvious 'confirm' parameter (has to be true), which is real added value, but farmId and bookingId are left to the schema and inferred meaning. Partial compensation against a total coverage gap.

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

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

The description names a specific verb and resource ('mark a rental paid/active') and pins down the exact state transition (pending_payment → active), so the effect is unambiguous. It does not, however, explicitly distinguish itself from the nearby sibling set_rentahatch_listing_active, leaving a small risk of confusion between booking vs listing activation.

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

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

Usage context is clear: this is the 'manual' path to activation and is gated to SuperAdmin, which tells the agent when it is appropriate. No alternatives or when-not-to-use conditions are named, so it stops short of a full routing statement.

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

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

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

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

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

Two short sentences, front-loaded with the core action and zero padding. The second sentence is a little vague ('supports confirm and idempotency validation') but costs almost nothing.

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

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

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

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

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

Schema description coverage is 100%, so all six parameters including confirm, idempotencyKey, and hoursLogged are documented in the schema. The description adds no syntax or semantic detail beyond restating that confirm and idempotency are supported, so the baseline 3 applies.

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

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

States a specific verb and resource ('Mark a task as Completed') and discloses a side effect ('update recurrence'), so the agent knows this is a state transition rather than a creation or deletion. However it never names or distinguishes itself from the sibling task tools (create_task, delete_task, get_tasks), leaving that routing to inference.

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

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

There is no statement of when to use this versus delete_task or get_tasks, nor any prerequisites beyond the schema's confirm flag. The clause about confirm/idempotency is a capability note, not usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds that a confirm-dry-run flow and idempotency validation exist, which is mildly useful context beyond the annotations, but it does not explain what a dry-run returns, what happens on failure, or why idempotentHint is false while an idempotencyKey is accepted.

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

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

Two short sentences with no filler, and the core action is front-loaded in the first clause. Every sentence carries information an agent can use.

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

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

With no output schema, the description should say more about what creation returns and how the dry-run preview differs from a committed event, which it does not. Annotations and a fully documented schema cover the basics, so it is adequate but leaves meaningful gaps for a mutation tool.

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

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

Schema description coverage is 100%, so every parameter including confirm and idempotencyKey is already documented in the schema. The description only echoes the existence of confirm and idempotency handling without adding format, constraint, or default detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a new calendar event") and scopes it to the farm's timeline, which is enough to separate it from get_calendar_events and delete_calendar_event. It stops short of naming those siblings explicitly, so the differentiation is implied by the verb rather than stated.

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

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

The description gives no when-to-use, when-not-to-use, or alternative guidance. "Supports confirm and idempotency validation" only hints at the commit/dry-run mode, and even that condition is fully explained by the confirm parameter in the schema, not by the description.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the write-safety profile is covered. The description adds the deduping behavior, but it never says what happens on a dedupe hit (error, merge, skip) or what confirm=false actually returns, and "supports idempotency validation" sits in tension with idempotentHint=false without explaining that the key is what makes retries safe.

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

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

Two short sentences with no filler, and the core action is front-loaded ahead of the capability note. Nothing can be trimmed without losing information.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the action and two key behaviors but omits the dedupe outcome, error conditions, and required auth context. Annotations carry the safety profile, so this is adequate but leaves real gaps an agent would hit at call time.

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

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

Schema description coverage is 100%, so all nine parameters are already documented, including the deduping notes on email/phone and the dry-run semantics of confirm. The description only restates those same two concepts and adds no format, default, or constraint detail beyond the schema; baseline 3 is appropriate.

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

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

The description names a specific verb and resource ("Add a new customer to the CRM") and adds a distinguishing qualifier ("with deduping"). It separates the tool from read-oriented siblings like get_customer_details, though it never names a sibling explicitly, so it falls short of a 5.

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

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

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

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

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

Annotations already establish the safety profile (non-readonly, non-destructive, non-idempotent, closed-world), so the bar is lower. The description adds genuine context beyond them: a two-step draft/commit flow via confirm:true and the system-set createdBy=manual attribute. It omits permission requirements and failure behavior, keeping it from a 5.

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

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

Three compact fragments, zero filler, with the core action and the commit mechanism front-loaded. Every clause carries information the schema does not.

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 4-param create tool with no output schema, the description is adequate but leaves loose ends: what farmId identifies, what state the note is in without confirm:true, and how it relates to list_farm_notes. A little more detail would make the write flow unambiguous.

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

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

Schema description coverage is 0%, so the description must carry the load. It clarifies the expected date format (YYYY-MM-DD) and the commit role of confirm, but leaves farmId and content semantics to inference, so it only partially compensates for the gap.

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 ('Create') and resource ('Farm Note'), making it distinguishable from update_farm_note, delete_farm_note, and get_farm_note by name alone. It does not explicitly contrast itself with those siblings, so it falls short of a 5.

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

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

No statement of when to use this versus update_farm_note or the other note tools, and no prerequisites or exclusions. The only usage-adjacent detail is the confirm:true commit gate, which is behavioral rather than routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so safety is partly covered. Beyond that the description discloses two useful behaviors: duplicate/matching submissions are handled as upvotes rather than new records, and confirmation is mandatory before the write. It does not explain the confirm=dry-run flag or what a duplicate does to the caller.

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

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

Two sentences, no filler, and the core purpose is front-loaded ahead of the imperative guardrail. Every sentence carries distinct information; nothing could be cut without losing meaning.

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents farmId, title, description, area, confirm, and idempotencyKey. The description adds no parameter-level detail (e.g., that 'confirm' implements the confirmation requirement) and only implicitly gestures at the confirm flag. Baseline 3 applies.

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

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

The description uses specific verbs and a specific resource: 'Submit a new feature request or upvote an existing matching request.' An agent immediately knows this is a write into the feature-request backlog. It does not name the read counterpart (get_feature_requests) or otherwise differentiate itself from siblings, so it falls short of a 5.

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

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

It defines the two entry conditions ('new request' vs 'existing matching request'), which is real routing logic, and adds an operational rule ('ALWAYS ask for confirmation before writing'). It never names an alternative tool or an explicit when-not-to-use case, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral requirement (mandatory confirmation before writing), but says nothing about the dry-run/confirm semantics or idempotency behavior the schema implies. Adds some value over annotations but not rich context.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so all 8 parameters are documented in the schema, including the enum on 'source' and the dry-run meaning of 'confirm'. The description contributes no additional parameter meaning, which is acceptable at full coverage but earns only the baseline.

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

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

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

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

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

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

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the created entity starts in Draft state and requires a valid BOM recipe, but the phrases 'Supports confirm and idempotency validation' are thin and largely restate schema fields rather than explaining side effects, failure modes, or permissions. Note the mild tension with idempotentHint=false, though an explicit idempotencyKey legitimately provides request-level deduplication.

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

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

Two short sentences, front-loaded with the verb and resource, with no filler. The trailing 'Supports confirm and idempotency validation' sentence is the least informative part but is compact enough not to be wasteful.

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

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

For a 7-parameter create tool with no output schema, the description plus a fully-covered schema and annotations give an agent enough to invoke it correctly: entity created in Draft, BOM must be valid, confirm toggles commit vs preview. It omits what the response returns and error behavior on invalid BOM, which is minor given no output schema is declared.

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 7 parameters are already documented in structured form. The description adds no syntax, format, or constraint detail beyond the schema (the BOM requirement it mentions is already in the sku field description), so the baseline of 3 applies.

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

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

The description states a specific verb and resource — 'Create a new Draft manufacturing production order' — and adds scope qualifiers (Draft state, valid BOM recipe) that make it distinguishable from read-oriented siblings like get_production_orders. It stops short of naming or contrasting with any related tool (e.g., confirming/updating orders), so it is clear but not sibling-differentiated to a 5 level.

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

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

Usage is only implied: the mention of 'confirm' and 'idempotency validation' hints at the dry-run vs commit flow, but the agent must open the schema to learn that confirm=false is a preview. There is no explicit when-to-use, when-not-to-use, or alternative-tool 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 only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds real behavior beyond them — creation yields a DRAFT, quantity is validated against campaign.minQuantity and monthlyLimit, and the call has a side effect of opening a support ticket. It does not discuss permissions, reversibility of the draft, or the relationship between idempotencyKey and idempotentHint=false, so it is strong but not exhaustive.

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

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

Four short sentences, each carrying distinct information (what is created, what is enforced, side effect, commit flag, next tool). The most important scoping facts are front-loaded and nothing is repeated.

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

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

For a mutating tool with no output schema, the description covers the key agent questions: draft-vs-commit semantics, validation constraints, side effects, and the follow-up tool. It leaves permission/authorization requirements and what the response contains unstated, which is a modest remaining gap given full schema coverage and 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%, so the baseline is 3, but the description adds meaning the schema does not: the concrete minimum-quantity example ('20 pairs for wings') and the monthlyLimit ceiling that governs the quantity parameter. Other parameters (farmId, paymentMethod, paymentDetails) get no extra clarification in the description.

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

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

States a specific verb+resource ('Create a Draft Bulk-Supply farm shipment') with scope qualifiers ('Sell Parts', 'for this farm'), which is enough to distinguish it from siblings like express_supplier_interest or list_my_supplier_shipments. It stops short of naming a sibling it must not be confused with, so it lands just under the top band.

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

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

Gives clear operational context: the default is a preview and 'Set confirm:true to commit', plus an explicit next step ('update_supplier_shipment_tracking when shipped'). No when-not-to-use or prerequisite/auth conditions are stated, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so safety is largely covered. The description adds a genuinely useful confirmation requirement, but says nothing about the dry-run/confirm semantics, idempotency behavior, or that a ticket ID is returned.

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

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

Two short sentences, front-loaded with the action and ending with the operational constraint; no filler. It is perhaps leaner than ideal for an 8-parameter mutation tool, but nothing is wasted.

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

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

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

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

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

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

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

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

States a specific verb and resource ("Create a new support ticket"), which is enough for an agent to identify the action. However, it offers no differentiation from nearby siblings such as create_feature_request or reply_to_ticket, which share the support/ticketing domain.

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

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

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

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

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

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

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

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

Two short sentences with the action front-loaded and no filler. It is efficient, though its brevity contributes to the missing context noted elsewhere rather than being a model of dense concision.

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3 regardless. The description merely echoes the confirm and idempotencyKey parameters already documented in the schema and adds no syntax, defaults, or interaction details beyond them.

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

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

States a specific verb and resource ('Create a new farm management task'), which is enough to tell it apart from sibling creation tools like create_hive or create_calendar_event by resource. It stops short of naming any sibling or scope constraint explicitly.

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

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

'Supports confirm and idempotency validation' hints at a dry-run workflow but gives no when-to-use guidance, no prerequisites, and no routing to alternatives. Nothing tells the agent when this tool is the right choice over the many other create_* siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds value by stressing permanence ('Permanently delete') and mandating user confirmation, which is behavior the annotations do not express.

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

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

Two short sentences with zero filler; the action and its permanence come first, and the safety directive follows. Every clause earns its place.

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

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

For a destructive delete with full annotation coverage and full schema coverage, nothing material is missing. The confirmation requirement and permanence warning make the description sufficient for correct invocation.

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

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

Schema coverage is 100%, so farmId, eventId, and confirm are all documented in the schema itself. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema carries full coverage.

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

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

The description states a specific verb and resource ('delete a calendar event') and constrains the scope to 'this farm'. It is trivially distinguishable from siblings like create_calendar_event and get_calendar_events without opening any schema.

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

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

It gives an explicit imperative precondition ('ALWAYS ask the user to confirm first'), which is strong usage guidance for a destructive tool. It does not name an alternative tool or spell out when-not-to-use, but the sibling create/get tools make the intent clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that except the confirm flag hint; it never says whether the delete is permanent or recoverable, what permissions are required, or what happens on failure.

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

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

Two short fragments with no filler force the essential facts to the front. It is terse to the point of under-specification, but nothing in it is wasted text.

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

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

For a destructive, non-idempotent mutation with no output schema and no annotation-supplied detail about consequences, the description is too thin. An agent lacks the permanence, permission, and error-handling context it would need to call this safely.

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 of explaining farmId, noteId, and confirm. It only touches confirm ('confirm:true'), implying the otherwise-optional boolean must be set true, and says nothing about the two required id parameters or their format.

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

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

The description states a specific verb and resource ('Delete a Farm Note'), which is unambiguous and matches the annotations' destructiveHint. It does not, however, differentiate this tool from adjacent siblings like delete_task, delete_calendar_event, or update_farm_note beyond the resource 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?

There is no guidance on when to delete versus archive, update (update_farm_note), or simply leave the note, nor any prerequisite or irreversibility warning. The only instruction, 'confirm:true', is a parameter detail rather than usage context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description reinforces irreversibility ('Permanently') and adds a mandatory user-confirmation step, which is genuinely new behavioral guidance beyond the structured fields. It does not say whether related records (time logs, etc.) are also removed.

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

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

Two short sentences, zero filler, with the destructive scope stated first and the confirmation requirement immediately after. Nothing to trim.

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

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

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

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

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

Schema description coverage is 100%, so both IDs and the confirm flag are already documented in the schema, establishing the baseline of 3. The phrase 'in this farm' loosely ties to farmId but adds no format, constraint, or example beyond the schema text.

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

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

States a specific verb+resource ('Permanently delete a task') and scopes it ('in this farm'), so an agent knows exactly what is removed. It does not name or contrast with any sibling (e.g., complete_task, delete_calendar_event), leaving differentiation to inference.

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

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

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

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

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

With annotations already covering safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds real behavioral context: it never sends, it persists into the farm's Email Assistant and pre-fills the QuailOS reply box, it returns a draftId, and it requires Owner/admin read/write AI keys. These are non-obvious side effects and auth requirements not derivable from 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?

Four compact sentences with the key facts (draft, never sends, where it lands, return value, auth) front-loaded. Dense but each sentence carries information; only minor tightening is possible.

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

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

For a 7-parameter mutation tool with no output schema and full schema coverage, the description supplies everything an agent needs: the side-effect surface, the return value (draftId), the auth requirement, and the recipient constraint.

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 seven parameters including defaults and constraints. The description restates the recipient default and participant rule but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (create) and artifact (reply DRAFT) scoped to an Email Assistant conversation, and immediately negates the obvious confusion with 'Never sends.' An agent can distinguish this from send_email without opening either schema.

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

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

Clarifies the core condition (draft, not sent) and points at the downstream alternative by noting the returned draftId is 'usable with send_email.' It also states the recipient default and participant constraint. It stops short of an explicit 'use this when you want to stage a reply rather than send one' rule, so it is strong but not fully prescriptive.

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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely useful context beyond them: role gating, the free-vs-paid outcome difference, and that paid courses yield a payment link rather than an enrollment. It does not explain how 'confirm' gates the action or what the idempotency key does, so it falls short of a 5.

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

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

Three tight sentences, front-loaded with the action and scoping, then prerequisites, then the paid-course caveat. No filler, though the parenthetical preview clause is a slight interruption to the main flow.

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 4-param mutation with no output schema and only 50% schema coverage, the description covers role requirements, idempotency expectation, and the free/paid outcome, which is decent. However, it leaves the required idempotencyKey and the confirm gate undocumented, so an agent knows the 'when' better than the 'how'.

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%: courseId, idempotencyKey, and (partially) confirm lack inline descriptions, and the description does not compensate by explaining any of them. It hints at a preview/confirm mode without mapping it to the 'confirm' parameter name, leaving the required idempotencyKey entirely unexplained.

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

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

States a specific verb+resource (enroll farm in a QuailOS Academy course) and distinguishes from siblings like get_academy_course, list_academy_courses, and list_my_academy_enrollments. The added 'preview free eligibility' mode slightly muddies a single-purpose read, but the core action is unmistakable.

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?

Provides real preconditions: requires owner, admin, or manager role, and explicitly excludes paid courses (they return a payment link and cannot be auto-enrolled via MCP). It does not name an alternative tool for the preview path, so no explicit when-instead guidance, but the constraints are concrete.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false. The description adds genuinely new behavioral context beyond them: the write creates a Pending farmInterest AND opens a support ticket, requires a supplier write-role key, and is a dry-run unless confirm:true. No contradictions 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?

Three compact sentences, front-loaded with the purpose, followed by side effects, prerequisites, and the commit flag. Nothing is redundant and no sentence restates the structured fields verbatim.

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

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

For a mutating tool with no output schema and rich annotations, the description covers the eligibility scope, authorization requirement, side effects, and dry-run behavior. It omits what happens on failure or what the tool returns, but nothing critical for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented; baseline is 3. The description reinforces confirm's dry-run-vs-commit semantics but adds no syntax, format, or validation detail 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?

States a specific verb+resource ('Show interest in a ... Supply Opportunity for this farm') and names the concrete side effects (Pending farmInterest, support ticket). It is clearly not any of the sibling list_/get_/log_ tools, but it never names list_supplier_opportunities as the discovery counterpart, so sibling differentiation is implied rather than 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?

Gives the eligibility condition (DIRECT_SHIP or any Active opportunity), the prerequisite (farm AI key with supplier write role), and the commit gate (confirm:true). It stops short of stating when to prefer this over related tools such as create_supplier_shipment or list_supplier_opportunities.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the output is a set of sire/dam pairings rather than a single answer, but it says nothing about ordering, ranking, or what happens when no pairing is viable.

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

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

A single sentence that front-loads the lookup type and then states the target and output shape; no wasted clauses. The 'Perform a reverse genetic lookup to' preamble is slightly ceremonious but does not obscure the core action.

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

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

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

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents target_variety (name or ID, case-insensitive) and limit (default 10). The description adds no format, matching, or truncation detail beyond what the schema provides, making the baseline 3 correct.

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

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

The description gives a specific verb (find) and resource (all possible parent pairings, sire and dam) plus the goal (producing a targeted plumage variety), which is far more informative than the tool name alone. It does not explicitly distinguish itself from the sibling predict_quail_cross, which appears to be the inverse operation, so it stops short of a 5.

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower, and the description still adds real behavior: media fields (videoId, pdfUrl) are conditionally returned based on free-preview status or enrollment plus a valid AI key, and locked lessons yield teasers only. It does not say what happens on an unpublished/unknown courseId or whether missing enrollment errors or degrades.

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

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

Two sentences, front-loaded with the core purpose and then the media-gating caveat; no filler. Slightly dense in the second sentence but every clause carries information.

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

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

No output schema exists, and the description does explain the conditional shape of media fields, which is the main return-value ambiguity. However the role of farmId, the error/teaser behavior for unpublished courses, and the enrollment/key prerequisites are left implicit, leaving gaps for a tool whose parameters are entirely undocumented in the schema.

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

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

Schema description coverage is 0%, so the description carries the full burden for both parameters, yet it never explains what farmId is for or when it must be supplied, nor the expected format of courseId. The phrase 'enrolled/tutor farms with a valid AI key' hints at farm context but does not tie it to the farmId parameter.

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

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

States a specific verb and resource ('Get one published Academy course with modules/lessons metadata'), and the singular 'one' plus 'published' scoping cleanly distinguishes it from the sibling list_academy_courses. An agent can pick between the two without opening a schema.

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

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

The singular 'Get one' implies this is the detail view used when a specific courseId is known, versus listing all courses, but no alternative is ever named and there is no explicit when/when-not guidance (e.g. what to do if the course is unpublished). Usage is inferable rather than 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the authorization requirement, which is useful context, but it does not address pagination, result size, or scope limits.

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

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

Two short sentences, with the action and returned resources front-loaded before the authorization note. No filler, though the trailing apiKey clause is slightly confusing rather than earning its place.

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

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

With no output schema, the description usefully enumerates the returned entities (yards, hives, queen statuses, varroa inspections), which is exactly what an agent needs to judge relevance. The only gap is the unexplained apiKey authorization requirement that has no corresponding parameter.

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

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

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

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

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

States a concrete verb (Retrieve) and enumerates the resources returned: yards, hives, queen statuses, varroa inspections. This separates it from generic siblings like get_bird_batches or get_egg_collections, though it does not explicitly name which sibling to prefer.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond that: the result set spans both active and archived batches. It says nothing about pagination behavior or ordering, which the schema only partially implies.

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

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

A single front-loaded sentence with the verb first and no filler. Every word earns its place.

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

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

For a simple read-only list tool with full schema coverage and annotations carrying the safety profile, the description is nearly sufficient. Minor gaps remain around pagination semantics, but no output schema is needed to explain return values.

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

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

Schema description coverage is 100%, so farmId, limit and cursor are all documented in the schema itself. The description adds no additional semantics (e.g. whether farmId scopes the query or whether cursor is opaque), so the baseline of 3 applies.

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

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

The description gives a specific verb ('Retrieve') and resource ('poultry census batches from the flock inventory'), which cleanly separates it from the write sibling log_bird_batch. It does not explicitly name or contrast with any sibling, so it falls short of a 5.

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

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

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

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

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

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

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

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

Two tight sentences with the resource and content scope front-loaded and the prerequisite trailing. No filler or repetition.

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

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

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

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

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

Schema description coverage is 100%, so all three parameters (farmId, startDate, endDate) are already documented with types and format hints. The description only restates that farmId is required and adds nothing about the date filter syntax, so baseline 3 applies.

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

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

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

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

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

Usage is implied by the content-type list and the farmId/apiKey prerequisite, but there is no explicit when-to-use versus alternatives (e.g., get_tasks for pure task lists) and no exclusions. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds an authorization requirement (farmId and apiKey), which is useful context beyond the annotations, but it says nothing about pagination or return scope despite cursor/limit params.

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

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

Two tight sentences with the core action front-loaded and no filler. Efficient, though the auth sentence could be integrated more naturally.

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

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

For a read-only lookup tool whose annotations cover safety and whose schema fully documents parameters, the description is nearly complete. It could hint at what the 'detailed profile' returns, but with no output schema that is a minor gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no syntax or constraints beyond what the schema provides for emailOrName, limit, or cursor, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (detailed profile of a specific customer) with the lookup key (email or name). It clearly distinguishes a read operation from the sibling create_customer, though it does not name that sibling explicitly.

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

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

Offers no when-to-use or when-not-to-use guidance and no routing to alternatives such as create_customer. The only contextual hint is 'by email or name,' which is really parameter detail rather than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered elsewhere. The description adds a useful auth requirement (apiKey authorization), but says nothing about pagination behavior or result shape beyond what the schema already encodes.

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

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

Two sentences, zero filler, with the core action front-loaded and the constraint second. Nothing needs trimming.

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

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

With no output schema, the description carries some burden for describing returns; it does name 'logs and collection counts' but gives no shape, ordering, or pagination expectations. Annotations and full parameter coverage compensate for much of the rest, leaving it adequate but thin.

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

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

Schema description coverage is 100%, so the schema fully documents limit, cursor, farmId, startDate and endDate including timezone semantics. The description only restates the farmId requirement, adding no meaning beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve daily egg production logs and collection counts'), which is clearly distinct from the write sibling log_eggs. It does not explicitly name or contrast with any sibling, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives (e.g., log_eggs for writing, or date-range scoping decisions). The only condition stated is a permission prerequisite ('Requires farmId and apiKey'), which is not usage guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive context beyond them: attachments are metadata only with no contents or links, open AI drafts for the thread are included, and email content is untrusted and must not be acted upon. The injection warning is exactly the kind of behavioral disclosure an agent needs.

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

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

Three tight sentences, front-loaded with what is returned and followed by the two hard constraints (auth scope, untrusted content). No filler or repetition of 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 carries the return-shape burden and does so: plain text body, thread messages, drafts, and attachment metadata only. Combined with the 100% schema coverage and rich annotations, an agent has everything needed 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 description coverage is 100%, so fetchFull, maxBodyChars, and includeThread are already documented in the schema. The description reinforces the thread/draft scope but adds no syntax or default information beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one Email Assistant message') and immediately scopes what comes back: sanitized plain text, conversation thread, and open AI drafts. This clearly distinguishes it from the sibling list_emails and from draft_email_reply.

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

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

It gives a hard prerequisite ('Owner/admin AI keys only') and the schema ties emailId to list_emails, so the agent knows the retrieval path. It does not, however, state when to prefer this over siblings like list_emails or get_ticket_thread, or any exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that retrieval is keyed by noteId, and says nothing about return content, not-found behavior, or access requirements, so it contributes little beyond the structured fields.

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 compact sentence with the lookup key front-loaded and no filler. It is efficient, though the brevity borders on under-specification rather than true conciseness.

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 single-record getter with no output schema or nested objects, the description is minimally adequate: the agent knows what it retrieves and by which id. However, with two undocumented parameters and no return/error context, it leaves gaps an agent may need to fill.

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 both farmId and noteId are undocumented in the schema. The description mentions noteId only as a lookup key and never explains farmId or the relationship between the two, so it does not compensate for the coverage gap.

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

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

The description gives a specific verb ('Get') and resource ('Farm Note') scoped to a single record ('one ... by noteId'), which cleanly distinguishes it from list_farm_notes. It does not explicitly name the sibling alternatives (list/create/update/delete_farm_note), so it falls short of a 5.

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

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

There is no guidance on when to use this versus list_farm_notes, nor any prerequisite or error condition mentioned. The only implied usage is the presence of a noteId in hand.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds only 'Public', which usefully signals no authentication is needed, but adds little else about behavior or failure modes.

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

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

Two short, front-loaded sentences with no filler. Efficient, though the brevity borders on under-specification for a tool with an undocumented 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 single-record read with full annotation coverage and no output schema, the description is nearly adequate. However, with 0% schema coverage it should have clarified that exactly one of slug/articleId is needed, which it does not.

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% and both parameters are undocumented in the schema, so the description carries the burden. It partly compensates by naming the two identifier types ('id or slug'), but does not clarify that one of the two is required, the expected format, or precedence if both are supplied.

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

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

States a specific verb (get) and resource (Farm Times article), with the lookup key included. It implicitly distinguishes itself from list_farm_times_articles and list_farm_times_headlines by specifying 'one article', though it never names those siblings explicitly.

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

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

'Get one Farm Times article by id or slug' plus 'Public read-only' implies the context (single-item fetch, no auth) without stating when to prefer this over list_farm_times_articles or what happens if the article does not exist. Usage is inferable but not 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the authorization requirement (apiKey), which is genuinely beyond the annotations, but says nothing about pagination behavior despite limit/cursor parameters existing.

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

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

Two short sentences with the core purpose front-loaded and no filler. The second sentence slightly restates the schema's required farmId, but the auth note earns its place.

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

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

For a read-only listing tool with a fully documented schema and no output schema, the description is nearly sufficient — an agent knows what it lists, whose data it returns, and what auth it needs. Only return-shape/pagination expectations are left implicit.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (limit, cursor, farmId, status, startDate, endDate). The description adds no filtering syntax, date-format, or status-value detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('feature requests') with a scope qualifier ('submitted by this farm'). It is distinguishable from the sibling create_feature_request, though it never explicitly names that sibling as the write counterpart.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one piece of behavioral context beyond that—the apiKey authorization requirement—but says nothing about return shape, pagination, or scope limits, so it earns a modest 3.

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

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

Two short sentences with the primary purpose front-loaded and no filler. The bundling of three distinct resources in one clause is slightly dense but not wasteful.

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

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

For a single-parameter read-only getter with no output schema, the description names the three data sets it returns and the auth requirement, which is enough for an agent to call it correctly. It could say more about what the response looks like, but the gap is minor.

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

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

There is a single parameter with 100% schema description coverage ('The unique farm ID'), so the schema already documents it fully. The description merely restates that farmId is required and adds no format or constraint details beyond the schema; baseline 3 applies.

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

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

States a specific verb (Retrieve) and enumerates the resources returned: active feed inventory, feed purchases, and feed mill logs. This is clear enough that an agent can tell it is a read of feed-related data, though it does not explicitly contrast itself with the write-side sibling log_feed_purchase.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the apiKey authorization requirement, which is genuinely useful context not in the annotations, but it says nothing about the optional month filter's behavior or the return shape.

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

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

Two sentences with no filler, purpose front-loaded ahead of the authorization requirement. Efficient and easy to parse, though minimal.

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

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

For a read-only retrieval tool with no output schema, the description usefully enumerates the returned data categories and the auth prerequisite. Minor gaps remain around month-filter behavior and result size, but nothing critical is missing.

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

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

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

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

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

States a specific verb (Retrieve) plus the resource and the exact data categories returned (expenses, income, cash flow, P&L), which distinguishes it from nearby siblings like get_transactions and get_orders. It does not explicitly name an alternative, so it falls short of a 5.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and idempotency profile is fully covered. The description adds one genuinely new behavioral fact — the farmId + apiKey authorization requirement — but says nothing about pagination behavior or result shape despite eight parameters including limit and cursor.

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

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

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

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

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

There is no output schema, so the description could reasonably be expected to say more about what a returned hatch batch contains, and it omits any mention of pagination despite having limit/cursor parameters. Annotations carry the safety profile, leaving the description merely adequate rather than complete.

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

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

Schema description coverage is 100%, so every parameter (limit, cursor, status, startDate, endDate, variety, incubator, farmId) is already self-documented. The description echoes only farmId and adds no filter semantics, date format guidance, or interaction rules beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Retrieve incubation and hatch batches"), which is enough to separate it from write siblings like log_hatch_set and log_hatch_result. It does not, however, distinguish itself from the closely-named read sibling get_bird_batches, which an agent could plausibly confuse it with.

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

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

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

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuinely non-obvious trait: the item URL is withheld when the farm's tier is below item.minTier (default Silver) and an upgrade message is returned instead. That conditional output behavior is exactly the kind of context structured fields do not carry.

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

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

Two short sentences with no filler; the core operation is stated first and the conditional gating caveat immediately follows. Every clause carries information.

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

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

There is no output schema, so the description usefully flags the one return-value variant an agent must anticipate (omitted URL plus upgrade message). It leaves the rest of the item payload and the error case of an unknown itemId unaddressed, but for a 2-param read tool with covering annotations this is nearly 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 description coverage is 0% for both required parameters, so the description must compensate and largely does not: it never explains what farmId or itemId are or their format. The reference to "farm tier" and "item.minTier" only obliquely suggests that farmId selects the tier used for the gating check.

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+resource ("Get one Library item") and the singular "one" implicitly contrasts with the sibling list_library_items. It is clear what it does, but it never names the sibling or states that it requires an existing itemId.

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

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

There is no statement of when to use this tool versus list_library_items or other get_* tools, and no prerequisite guidance beyond the schema's required fields. The tier-gating sentence describes output behavior, not when-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the content is public (no auth) and it explicitly disambiguates the signup path from the buy board, which is behavioral insight not present in structured fields.

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 compact sentences, front-loaded with the tool's subject before the disambiguation clause. Dense and waste-free, though the trailing fragment about '/make-money-with-quail' assumes the reader already knows the route context.

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

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

For a parameterless read-only guide fetch with no output schema, the description supplies enough to call it correctly: what the guide covers, its audience, and its public nature. It could say more about the guide's actual contents or format, but that is a minor gap.

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

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

The tool takes zero parameters and schema description coverage is 100%, so the baseline is 4. Nothing in the description is needed to clarify inputs, and there are no hidden parameter semantics to explain.

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

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

The description names a specific resource (a signup-oriented guide about earning via Supply Opportunities/Undique) and states its subject matter concretely. It partially distinguishes itself by contrasting against the 'buy board' concept, though it doesn't explicitly differentiate from sibling guide tools like get_academy_course or get_public_wiki_pages.

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

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

Usage context is implied by describing the guide as 'signup-oriented' and clarifying that /make-money-with-quail is Rent-a-Hatch vendor signup rather than the buy board. However, there is no explicit 'use this when...' statement or named alternative tool to route 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the authorization requirement (farmId and apiKey), which is genuinely new context beyond the annotations. It says nothing about the shape/volume of results, but with annotations carrying the behavioral burden a 3 is appropriate.

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

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

Two short sentences, no filler, and the resource scope is front-loaded before the prerequisite. Every sentence earns its place.

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

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

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

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

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

There is one parameter with 100% schema description coverage, so the schema fully documents farmId. The description restates the farmId requirement (and adds an apiKey that is not in the schema, likely an auth header), but adds no meaning about the parameter's format or constraints beyond the schema. Baseline 3 applies.

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

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

The description gives a specific verb ("Retrieve") and names the resources precisely: meat processing logs plus cold storage/freezer inventory. This distinguishes it from the many other inventory/log siblings such as get_feed_inventory and get_egg_collections. It stops short of explicitly naming a sibling to route away from, so it lands at a clear 4 rather than 5.

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

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

It states a prerequisite ("Requires farmId and apiKey authorization") but gives no when-to-use guidance or alternatives among the many other get_* inventory/log tools. An agent must infer on its own when meat inventory is the right call versus feed inventory or bird batches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the useful scoping detail that only 'registered' logs are returned, but says nothing about ordering, pagination behavior, or date-range semantics despite limit/cursor/startDate/endDate 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?

A single front-loaded sentence naming verb, resource, and purpose with zero filler. Nothing is wasted or buried.

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

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

With annotations covering safety and a 100%-documented schema covering all parameters, the description is nearly sufficient for a read-only list tool. The one remaining gap is pagination/ordering expectations, which matter for a cursor-based endpoint but are only inferable from the schema.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, and the baseline is 3. The description contributes no additional parameter meaning such as default date windows or how farm time interacts with ISO dates.

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

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

States a specific verb ('Retrieve') and resource ('registered vehicle mileage logs') plus the domain purpose ('tax and expense auditing'), so an agent knows exactly what comes back. It does not explicitly distinguish itself from close siblings such as log_mileage (the write counterpart) or get_time_logs, which keeps it below 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 stated purpose ('for tax and expense auditing') implies when the data is wanted, which is weak but real usage context. There is no explicit when-to-use, no prerequisites, and no routing to alternatives like log_mileage or list_vehicles.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes the fact that this is a lookup/mapping operation against a federal regulatory dataset, but adds nothing about result shape, result size, or how partial matches behave.

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

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

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

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

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

For a parameterless-required, read-only lookup with a fully documented input schema and no output schema, the description covers what an agent needs to decide to call it. It could be marginally stronger by signaling that results are a code mapping rather than a full variety record, but nothing essential is missing.

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

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

Schema description coverage is 100%, so limit, query, cursor and category are all documented in the schema itself. The description adds no extra semantics such as which category values pair with which variety types, so the baseline 3 applies.

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

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

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

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

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

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

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

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

Annotations already declare readOnly/idempotent/no-destructive, so the bar is lower, yet the description adds substantial behavior: damage contacts are masked by default, includeContact is gated to owner/admin read/write keys, denied for read-only keys and other roles, and every access is audit-logged. This is exactly the authorization and privacy context an agent needs.

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

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

Front-loads purpose, then the includeContact caveat, then authorization. Slightly dense with a trailing 'Read-only. Requires farmId and apiKey authorization' that partially repeats annotations, but nothing is wasted and it reads in priority order.

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 still conveys the return shape (eggs set/hatched, star rating, comments, contactMasked, contact) and the notFound/authorization edge cases. For a 12-parameter read tool this is complete enough to invoke 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 baseline is 3, but the description adds real meaning beyond the schema for includeContact (permission gating, audit logging, what `contact` contains) and for feedbackId (single-report fetch, other filters ignored). It leaves limit/cursor/date/rating filters to the well-documented schema.

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

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

States a specific verb+resource (list customer feedback on online orders) and enumerates the two report types, hatch-rate and shipping damage, which distinguishes it from siblings like get_orders and get_customer_details. An agent can identify the correct tool without opening the schema.

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

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

Explains the two access patterns clearly: use feedbackId to fetch a single report, use includeContact:true only when the full contact is needed and the caller qualifies. It does not name a sibling alternative, but the conditional usage guidance is concrete rather than implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description still adds real behavior beyond that: the exact response envelope keys, cursor stability rules (nextCursor null on last page, olderThanDays frozen at page 1), and data-privacy boundaries (no street, phone or email). Strong, though it does not mention rate limits or auth-scope nuances.

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

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

Front-loads the purpose and return shape, then groups pagination, stale-order guidance, date semantics, field availability and filters. Dense but every section earns its place; slightly long for an agent skimming, but no filler sentences.

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

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

With 11 parameters and no output schema, the description compensates fully by enumerating the return fields, pagination contract, filter interactions and auth requirement. An agent can call this correctly without further reference.

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 baseline is 3, and the description genuinely adds meaning on top: date filters interpreted as whole local days (America/New_York, inclusive), salesChannel precedence for Shopify-synced orders, normalized 2-letter shippingState, and the constraint that filters must stay identical across pages.

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

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

States a specific verb and resource ('Retrieve the farm's sales orders') and immediately scopes it to three sources (manual, connected stores, incoming dropships) with an ordering rule (newest first). This is enough for an agent to distinguish it from siblings like get_order_feedback or get_transactions.

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

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

Gives explicit when-to-use guidance: paginate by re-calling with the SAME filters and nextCursor verbatim, and rules out offset/page. It also names a concrete alternative workflow for stale-order checks (unfulfilledOnly + olderThanDays/createdBefore 'instead of paging through everything').

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 fully cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the agent knows this is a safe, repeatable read. The description adds only that scope is 'farm inventory'; it discloses nothing about pagination, result ordering, or filtering behavior beyond what the schema already carries.

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 wasted words. It is arguably under-specified rather than bloated, but structurally clean.

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 complete annotations and a fully documented schema, the description is borderline adequate. With no output schema, a note on the return shape or ordering would help, and routing against create_production_order is missing.

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

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

Schema description coverage is 100%, so all four parameters (sku, limit, farmId, status) are already documented in the schema, including the enum values and the default/max on limit. The description adds no syntax or filtering semantics beyond that baseline.

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

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

The description states a specific verb ('Retrieve') and resource ('manufacturing production orders'), making the tool's function clear at a glance. It does not, however, differentiate itself from the sibling create_production_order or explain its relationship to retrieval tools like get_orders.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g., create_production_order for writes, or other get_* inventory readers), and no stated prerequisites. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are limited to the public directory and names the returned fields, which is modest extra context, but says nothing about result limits, pagination, or empty-result behavior.

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

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

Two short sentences, front-loaded with the resource and immediately followed by the returned fields. No filler or redundancy.

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

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

For a simple, read-only, zero-required-parameter search tool with fully documented schema and annotation-covered safety, the description is nearly sufficient. Only minor gaps remain around result size and whether an empty query returns anything.

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

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

Schema description coverage is 100%, so both parameters (query, state) are already fully documented in the schema, and the description restates that searching covers name/bio/specialties. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb (search/retrieve) and resource (QuailOS public farm directory), and lists the returned fields. The 'public' qualifier and 'farm directory' scope distinguish it from sibling read tools like get_public_wiki_pages, though no sibling is named directly.

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

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

The description implies a search use case but gives no explicit when-to-use guidance, no prerequisites, and no alternatives. An agent must infer that this is the tool for finding farms rather than, say, beekeeping apiaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope ('published', 'public') but says nothing about result volume, pagination, or ordering, which the presence of a cursor parameter makes relevant.

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

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

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

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

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

For a read-only search endpoint with no output schema and fully documented optional parameters, one sentence is nearly enough. However, it omits the pagination behavior implied by the cursor parameter and the default result count, which an agent would need to page through results correctly.

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

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

Schema description coverage is 100%, so all three parameters (limit, query, cursor) are already documented in the schema. The description implies keyword search matching what 'query' does but adds no extra format, default, or pagination semantics beyond the structured data.

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

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

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

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

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

There is no statement of when to use this tool versus alternatives, nor any prerequisite or exclusion. The only hint is the word 'search', which implies a keyword-driven lookup but leaves the agent to infer the selection conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavioral information beyond that: unapproved videos are hidden from results unless the caller is a SuperAdmin, which explains unexpected 'not found' outcomes.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the visibility caveat follows. Every clause earns its place.

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

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

For a simple single-item read with no output schema and a read-only annotation profile, the description covers the resource, lookup keys, and access caveat. It stops short of describing behavior for missing/invalid ids or what happens when both identifiers are omitted, which is the main remaining gap.

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

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

Schema description coverage is 0%, so the description carries the burden. Saying 'by doc id or YouTube videoId' maps the two bare schema properties (id, videoId) to meaningful concepts, which is real added value. However, it does not clarify that neither parameter is required, whether both may be supplied, or which takes precedence when both are given.

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

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

States a specific verb ('Get') and resource ('one QuailOS TV video') and names the two lookup keys (doc id / YouTube videoId). The singular 'one' implicitly distinguishes it from the sibling list_quailos_tv, so an agent can route correctly without opening the schema.

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

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

The 'Non-approved hidden unless SuperAdmin' clause gives useful visibility context, but there is no explicit when-to-use guidance, no statement of prerequisites (e.g. SuperAdmin privileges), and no named alternative against which to choose this tool.

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 the read-only, idempotent, non-destructive profile, so the safety bar is met. The description adds genuinely useful context beyond the annotations: the SuperAdmin authorization requirement and the fact that payoutDetails.details is masked in the response.

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 terse sentences with no filler; the lookup keys come first, followed by the auth constraint and the masking note. Every sentence carries distinct 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 single-entity read tool with no output schema and full annotation coverage, the description covers the essentials: what it retrieves, the auth requirement, and a notable response-masking behavior. It could be marginally stronger by noting the list alternative or partial-result behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates 'by farmId or slug' but the schema documents three parameters including vendorFarmId, and the text does not clarify the relationship between farmId, slug, and vendorFarmId, so it adds little over 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?

Specific verb+resource ('Get one Rent-a-Hatch vendor') with the lookup keys named ('by farmId or slug'). The singular 'one' implicitly distinguishes it from the sibling list_rentahatch_vendors, though it never names that sibling explicitly.

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

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

Provides the 'SuperAdmin only' access prerequisite but gives no explicit when-to-use guidance or exclusion criteria, and never names list_rentahatch_vendors as the bulk alternative. Usage must be inferred from the singular/plural distinction.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered structurally. The description adds the authorization requirement (farmId + apiKey), which is genuine extra context, but says nothing about pagination behavior or result ordering beyond what the schema implies.

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

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

Two tight sentences with the resource and scope front-loaded and zero filler. It is appropriately sized for a simple list tool, though the second sentence is largely a restatement of a required field already in the schema.

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

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

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

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

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

Schema description coverage is 100%, so all six parameters including limit, cursor, status, and date filters are already documented. The description only echoes the farmId requirement and adds no format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List), resource (support tickets) and scope (created by this farm), so the agent knows what it returns and that it is farm-scoped. It does not explicitly distinguish itself from close siblings like get_ticket_thread or get_feature_requests, which keeps it just short of a 5.

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

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

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

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

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

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

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

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

Two short sentences with the core purpose front-loaded, followed by the auth requirement. Efficient and readable, though the second sentence partly restates a parameter already in the schema.

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

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

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

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

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

Schema description coverage is 100%, so both farmId and the optional status filter are documented in the schema. The description's 'active/pending' phrasing loosely maps to the status filter but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (farm management tasks) with a scope qualifier (active/pending). An agent can distinguish it from create_task/delete_task/complete_task by the read orientation, though the description does not explicitly name those siblings.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the authorization requirement ('Requires farmId and apiKey authorization'), which is genuinely useful context, but it stops short of describing volume, pagination, or the shape of the returned thread.

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

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

Two short sentences with the purpose front-loaded and the prerequisite trailing, which is a sensible order. The apiKey clause is slight filler since it maps to no schema field, keeping this just under a 5.

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

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

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

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description restates farmId and mentions apiKey, which is not actually a declared parameter, so it adds no meaningful semantics beyond the schema.

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

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

States a specific verb ('Retrieve') and resource ('full reply history and messages thread of a support ticket'), which is clear and distinguishes the thread view from a list endpoint. It does not name sibling tools like get_support_tickets or reply_to_ticket to sharpen the boundary, so it falls short of a 5.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing further about pagination behavior, result shape, or whether the two resource types are returned together or separately; the phrase 'time clocks' also leaves ambiguity about whether clock entities or clock events are returned.

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

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

A single well-formed sentence with no filler, and the verb and resource are front-loaded. It is arguably too terse given the ambiguity it leaves, but nothing is wasted.

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

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

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

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

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

Schema description coverage is 100% with three documented parameters (farmId required, limit, cursor), so the schema carries the full burden. The description adds no meaning beyond the schema, which is the expected baseline when coverage is complete.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one behavioral nuance — that only 'manual' transactions are returned — but says nothing about pagination or date scoping despite limit/cursor parameters being present.

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

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

A single front-loaded sentence with the verb and resource up front and no filler. It is efficient, though it is arguably too terse to carry usage or return-shape information.

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

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

For a read-only list tool with full schema coverage and rich annotations and no output schema, the description covers the core purpose. It omits pagination behavior and any date/currency filtering semantics, leaving minor gaps for the agent.

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

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

Schema description coverage is 100%, so limit, cursor, and farmId are already documented in the schema. The description adds no additional parameter meaning, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Retrieve) and a specific resource (manual general ledger transactions) with the covered categories (expense, income, equity). The word 'manual' implicitly separates it from derived reporting tools like get_financial_pnl, but no sibling is named explicitly.

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

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

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

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds an authorization requirement (apiKey) not present in annotations, which is useful, but it mentions an apiKey that is not a declared parameter, which is slightly confusing.

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

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

Two short sentences, front-loaded with the purpose, with no filler. Size is appropriate for a simple read tool.

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

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

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

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

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

Schema coverage is 100% for the single farmId parameter, so the schema does the documentation work and the baseline is 3. The description adds nothing about farmId format or scope beyond what the schema states.

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

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

States a specific verb ('Retrieve') and two concrete resources (purchase orders, vendor profiles), so the agent knows what it returns. It does not, however, distinguish itself from the sibling get_orders, which an agent could easily confuse with the PO half of this tool.

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

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

The description gives no when-to-use context and names no alternative, even though get_orders sits in the sibling list and covers overlapping territory. The only guidance is an authorization prerequisite, not a usage condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Read-only' is largely redundant. The description does add non-annotation value by disclosing the category exclusion and that results carry price/freeForTiers hints, which tells the agent what the payload will contain.

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

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

Three terse, front-loaded fragments with no filler; the scope constraint and the read-only/safety note come early. The telegraphic style is efficient, though it reads as a note rather than a sentence.

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

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

For a simple two-parameter, optional-argument list tool with rich annotations and no output schema, the description covers scope and payload hints adequately. It is incomplete on the undocumented 'limit' parameter and on result-size/pagination behavior, which an agent would need to call it confidently.

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%: farmId is documented in the schema, but 'limit' has no description anywhere. The description mentions price/freeForTiers hints (an output trait) but says nothing about what limit controls, its default, or pagination, so it does not compensate for the coverage gap.

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 published QuailOS Academy courses') plus a scope constraint ('excludes Rent-a-Hatch category'), so the agent knows it returns a curated catalog rather than everything. It does not name the closely related siblings get_academy_course or list_my_academy_enrollments, so differentiation is only implicit.

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 when-to-use or when-not-to-use guidance is given; the agent has to infer that this is the browse-the-catalog entry point versus get_academy_course (single course) or list_my_academy_enrollments (personal). The 'excludes Rent-a-Hatch' note is scope, not routing guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds real value beyond that: auth gating (owner/admin keys), default ordering (newest first), the returned field set, and the pagination contract (nextCursor passed back verbatim with the same filters).

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

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

Four compact sentences, front-loaded with the mailbox scope and key facts. No wasted words; the ordering and pagination notes are placed sensibly. Slightly dense but 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?

With no output schema, the description helpfully enumerates returned fields (id, threadId, from, subject, snippet, date, folder, read flag) and covers auth, ordering, and pagination. Adequate for an 8-parameter list tool, though default folder/limit behavior is only in the schema.

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

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

Schema coverage is 100%, so every parameter (limit, query, since, until, cursor, farmId, folder, unreadOnly) is already documented in the schema. The description's cursor note ('passed back verbatim with the same filters') mostly restates the schema, adding little beyond the baseline.

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

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

States a specific verb (List) and resource (messages in the QuailOS Email Assistant inbox), clearly distinguishing it from get_email, send_email, and move_email by the plural-list scope. It does not explicitly name a sibling it is not, but the verb+resource is unambiguous.

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

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

It states the access requirement (Owner/admin AI keys only) and ordering (newest first), which imply when it can be used. However, there is no explicit guidance on when to use this versus get_email for a single message or draft_email_reply for responding, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds two genuine extras beyond the annotations: result ordering (newest first) and a UI locator (Office > Farm Notes). It says nothing about pagination behavior for cursor/limit or the size/shape of the returned set, so it is adequate rather than 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?

Two short sentences with the resource and scope front-loaded and no filler. The parenthetical UI path is slightly extraneous for an API consumer but is cheap and does aid disambiguation; nothing is padded.

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 no output schema, the description should at minimum explain how limit and cursor interact and what a returned page looks like, since the agent cannot learn that anywhere else. With zero parameter coverage and no output schema, the definition is under-specified for correct invocation despite the simple read-only nature of the tool.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and mostly fails it. The phrase 'for this farm' loosely implies the farmId parameter, but 'limit' and 'cursor' — the pagination contract an agent must use correctly — are never explained in either the schema or the description.

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 ('List Farm Notes') plus a scope qualifier ('for this farm'), which cleanly separates it from the singular get_farm_note and the mutating create_farm_note/update_farm_note siblings. However, it never names an alternative or explicitly distinguishes itself from those siblings, so it lands at clear-but-undifferentiated rather than fully self-routing.

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

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

There is no guidance on when to use this tool versus get_farm_note or get_farm_note-adjacent siblings, and no mention of prerequisites such as needing a valid farmId. The ordering note ('Newest first') is output behavior, not usage guidance, so the agent is left to infer the calling 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 readOnly, idempotent, openWorld, and non-destructive, so 'Public read-only' largely restates structured data. The one piece of genuine added value is the pagination instruction ('Paginate with cursor'), which tells the agent the result set is paged, but it stops short of stating page size, default limit, or ordering.

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

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

Three short, front-loaded sentences with no filler. 'Public read-only' is mildly redundant against the annotations, but the overall signal-to-length ratio is good.

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 public read tool with no output schema and annotations covering safety, the essentials are nearly covered, but the description never indicates what an article record contains or how results are ordered, and limit remains unspecified. Just adequate rather than complete.

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

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

Schema description coverage is 0%, so the description carries the burden for two parameters. It explains cursor's role ('Paginate with cursor') but says nothing about limit — no default, maximum, or behavior when omitted — leaving half the parameters undocumented.

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

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

States a specific verb (List) and resource (published Farm Times / community_news articles), which is enough for an agent to identify the operation. It does not differentiate from close siblings like list_farm_times_headlines or get_farm_times_article, so the boundary between 'articles' and 'headlines' is left to inference.

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

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

There is no explicit when-to-use guidance and no mention of alternatives, despite at least two closely related siblings (list_farm_times_headlines, get_farm_times_article). 'Public read-only' hints at context but is a property, not usage direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description's 'Public read-only' largely restates that; the only added behavior is the 'active' filter scope. No pagination or return-shape context is offered, 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?

Three short fragments, verb and resource front-loaded, zero filler. The telegraphic fragment style is efficient but slightly clipped compared to a full sentence, keeping it just under top marks.

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

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

For a parameterless, annotated, publicly readable list tool with no output schema, the description covers what is listed and what it is not. It could optionally hint at how many headlines or how they are ordered, but nothing required to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument, list-everything behavior by not mentioning any filters or IDs.

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

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

States a specific verb (List) and resource (Farm Times headlines), scoped to 'active' and clarified as 'system community news'. It also preempts the obvious naming confusion with sibling content tools (list_farm_times_articles) and with timeclock data. An agent can locate this among ~90 siblings without opening the schema.

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

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

'Public read-only' tells the agent this is unconditionally safe to call, and 'Not farm timeclock logs' is an explicit when-not guard against a genuinely confusable name. It stops short of naming an alternative (e.g., use list_farm_times_articles for full articles), so it is clear-but-not-exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description adds genuinely non-obvious behavior: a per-item tier gate that can return metadata with locked:true and no url plus an upgrade message, telling the agent to expect partial/degraded results rather than an error.

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

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

Two sentences, zero filler, and the identity of the tool is stated before the caveat about gated results. Nothing is redundant with the annotations.

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

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

For a read-only list tool with no output schema, the critical gotcha (locked items with no url) is covered. However, with 0% schema coverage the description never explains limit or the ordering/pagination behavior an agent needs to page through results, leaving a real gap for a listing tool.

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

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

Schema description coverage is 0% for both parameters, so the description carries the burden. "farmId" is only indirectly implied by the phrase "if farm below minTier"; the limit parameter and any pagination semantics are entirely undocumented in both schema and description.

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 QuailOS Library items") that an agent can distinguish from the singular get_library_item sibling by name alone. It does not explicitly contrast itself with that sibling or list_* alternatives, but the purpose itself is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g., use get_library_item for a single item). Usage is only implied by the verb "List" and the presence of farmId.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's '(read-only)' merely repeats the annotation rather than adding new context such as return format or scoping behavior; with annotations present, a 3 fits.

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

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

Two short sentences, no filler: the action/scope first, then the routing alternative. Every clause earns its place and the most important routing info is front-loaded.

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

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

For a simple single-parameter list tool whose annotations carry the entire safety profile and with no output schema required, the description covers the essential purpose and routing. The only gap is the undocumented farmId, which is minor at this complexity level.

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 single required farmId parameter is undocumented everywhere. The description's 'this farm's' only loosely implies the farm scoping and never names or explains farmId or its format, so it fails to compensate for the coverage gap.

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?

Uses a specific verb (List) plus the resource (this farm's Academy enrollments/progress), and explicitly routes away from enroll_academy_course. It does not address the other nearby sibling list_academy_courses, but the resource nouns are distinct enough to disambiguate.

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