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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true. The description adds real value by warning that a second call creates a duplicate, which directly reinforces the non-idempotent semantics. It omits auth/permission requirements, which keeps it 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?

Front-loads the core action, then layers domain role, a parameter hint, ordering guidance, and the duplicate warning. Every sentence carries a distinct piece of information with no filler.

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

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

For a 2-param create tool with full schema coverage and an output schema, the description covers the creation semantics, prerequisite ordering, duplicate risk, and the return value. Nothing an agent needs 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?

Schema coverage is 100%, so both parameters are already documented, including that managers may be given by name, email or id. The description restates this manager guidance rather than adding format or constraint detail beyond the schema, 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+resource ("Create a customer") and immediately clarifies its domain role (the entity that organisation projects are attached to and billed for). This lets an agent distinguish it from the many create_* 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?

Gives explicit ordering guidance (use before create_project when the customer doesn't exist) and a concrete precondition plus alternative (check list_customers first to avoid duplicates). Both the when-to-use and the sibling to consult are 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 non-read-only, non-idempotent, non-destructive, open-world behavior, and the description goes further by disclosing the validation rule (both project and task, or neither, is refused before any request is sent) and an entitlement prerequisite (Gryzzly's budget offer). The non-idempotency consequence is also made actionable via the list_discounts warning.

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

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

The scope constraint and the create-vs-update distinction are front-loaded, and every sentence carries either scope, routing, or a prerequisite. Slightly long across four sentences, but there is no filler or restated name/title.

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

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

For a mutation tool with an output schema available, the description need not explain return values, and it covers what matters: scope, sibling routing, duplicate-avoidance workflow, pre-request validation, and the budget-offer prerequisite. Nothing an agent needs to call 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 name, project, task, and amount are already documented, including the 'one of project or task' note. The description restates the one-of constraint and adds a small amount of enforcement detail (refused before any request), but supplies no new format, unit, or identifier syntax beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (grant) and resource (discount) plus the exact cardinality/scope: exactly one project OR one task, named or identified, with a name and an amount off budget. That level of precision separates it cleanly from update_discount, get_discount, and delete_discount 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?

Explicitly routes creation to this tool and modification to update_discount, and adds a concrete pre-call workflow: check list_discounts first because each call creates a new record. This is when-to-use, when-to-use-something-else, and a de-duplication guard in three sentences.

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?

Adds real behavioral context beyond the annotations: the refusal rule when time is already declared over those days, and that delete_declarations removes that time irreversibly. There is a mild tension with destructiveHint=false, since a conditional irreversible deletion is disclosed, though it defaults to false — the description is more informative than the hint, not contradictory, but the mismatch is worth noting.

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-loaded with purpose, then alternative routing, then the half-day encoding rule, then the destructive caveat. Four dense sentences with no filler; each clause 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?

Output schema exists, so return values need no explanation, and the mutation semantics are well covered. Remaining minor gaps: no indication of permission requirements for declaring leave on behalf of another user, and no date/timezone format hint for start_at, though the schema carries the parameter-level detail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics: the half-day encoding rule ('a single afternoon off is the same day twice, pm to pm') and the consequence of delete_declarations in relation to the refusal behavior. Those are genuinely useful beyond the per-property descriptions.

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

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

States a specific verb and resource ('Declare a leave period (days off) for a user'), including the default scope ('the current one by default'). It immediately separates itself from update_leave_period and list_leave_periods, so an agent can route without opening sibling schemas.

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

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

Explicitly says when to use it ('for holidays and absences') and names the two most confusable alternatives with their selecting conditions: update_leave_period to move an existing one, list_leave_periods to check existing ones first. That is exactly the routing guidance an agent needs before calling a create tool on a resource that can conflict with existing data.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is already covered. The description goes further with genuinely new behavior: duplicate creation on repeat calls, the implicit start-date default ('today is used when none is given'), and the cross-field invariant that a public project must not carry contributors. It stops short of permissions/auth or what the response contains.

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-loaded with the purpose, then ordered as constraints, defaults and the recommended call sequence. It is dense but nearly every clause carries actionable content; the 'Gryzzly needs a start date' framing is slightly verbose relative to the point it makes.

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 eleven-parameter create tool with an output schema, the description supplies the domain role, the defaulting behavior, the visibility/contributor invariant, the duplicate risk and the required next step. Nothing needed to invoke it correctly in sequence is missing.

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

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

Schema coverage is 100%, so the schema already documents all eleven parameters, including start_at's default and the contributors/public constraint. The description adds only a modest relational gloss ('A customer and managers or contributors can be named rather than identified'), which the schema fields largely restate. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource, then adds the conceptual role ('the container tasks and time are attached to'), which is exactly what an agent needs to place it in the domain model. It also names siblings (list_projects, create_task), so it is separable from create_task, create_customer and the other create_* tools 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?

Gives an explicit precondition ('Check list_projects first, since a second call creates a duplicate') and an explicit follow-up ('then add tasks with create_task, because time cannot be logged on a project without one'). The alternative/complementary tools and the conditions selecting them are stated outright rather than inferred.

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=true, so the safety profile is covered. The description goes beyond them by spelling out the consequence of non-idempotency ('Creates a new record on every call, so check list_purchases first'), the billing_policy side effect on budgets, and the prerequisite feature flag. It stops short of describing permissions or failure modes, keeping it at a 4.

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

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

Front-loaded with the core action and target, then the routing rule, then the duplicate warning and prerequisite. Nothing is padding. The billing_policy sentence is telegraphic ('add counts it in the budget, ignore records it only') and slightly awkward, which keeps it from 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?

With 8 parameters, all documented at 100% coverage, annotations, and an output schema that removes any need to describe return values, the description supplies what is left: the routing alternative, the mutual-exclusion constraint, the duplicate risk, and the feature prerequisite.

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 and the schema already carries the field-level detail. The description still adds value by stating the exactly-one-of constraint across project/task and that both accept 'name or id', plus a plain-language reading of billing_policy that the enum descriptions only partially convey.

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 ('Record a purchase') and immediately scopes it ('an expense outside declared time', 'against exactly one project or one task'). It explicitly distinguishes itself from update_purchase, which is the closest sibling, so an agent can route 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?

Gives the when (add a cost), the when-not (use update_purchase to change an existing one), and a concrete prerequisite workflow ('check list_purchases first to avoid duplicates'). It also names a hard external requirement ('Requires Gryzzly's budget offer'), which is exactly the kind of gating condition an agent needs before calling.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, open-world behavior; the description reinforces non-idempotency by warning that repeat calls duplicate. It also adds semantics the annotations cannot carry: container tasks take no time, subtasks name a parent, and tasks are the unit that log_time declares against.

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

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

Four sentences, front-loaded with the core purpose and then the operational caveats. Dense but each sentence carries a distinct fact (dependency, container semantics, duration format, duplicate risk); no filler.

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

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

With an output schema present, return values need no explanation, and the annotations cover the safety profile. The description fills the remaining gaps an agent needs: required context (project, optional parent), the log_time dependency, duration syntax, and the duplicate hazard.

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 14 parameters, so the schema already documents each field, including the duration format examples. The description restates is_container/subtask behavior and the 40h/90m duration format that the schema's own descriptions already provide, 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+resource (create a task) plus the scoping detail that it lives in a project identified by name or id. An agent can separate this from create_project, update_task, or delete_task from the description alone.

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

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

Explicitly routes the agent to list_tasks first and explains why (a second create call produces a duplicate), which is real when-to-use guidance. It also discloses the cross-tool dependency that log_time requires at least one task, though it never states an outright 'do not use when' 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value beyond that by disclosing a business rule that blocks the operation when projects are attached — a failure mode the annotations cannot express. It does not state reversibility or cascade effects, 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?

Two tight sentences with zero filler; the operation is front-loaded and the blocking precondition follows immediately. Nothing is padded or restated.

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

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

A destructive tool with an output schema and full annotation coverage needs only a crisp statement of action plus the non-obvious failure condition, both of which are present. The agent knows what it does, when it will be refused, and that the return shape is documented elsewhere.

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%: both 'customer' (name or id) and 'confirm' (must be true to delete) are fully documented in the schema. The description adds no syntax, format, or constraint detail about either parameter, 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 (delete) and resource (customer) in the first sentence, which cleanly separates it from the create_/update_/get_/list_ siblings by naming convention. It stops short of explicitly differentiating itself from adjacent deletion tools (delete_project, delete_task) in the way a 5 would require.

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 precondition 'Gryzzly refuses while projects are attached to it' implicitly tells the agent when this call will succeed, but there is no explicit when-to-use guidance, no statement of alternatives (e.g. detach projects first), and no mention of required permissions. Usage is implied rather than directed.

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context not in the annotations: deletion restores the discount amount to the project budget, which is the key downstream consequence an agent must know.

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

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

One sentence, no filler, with the resource and the important budget side effect both front-loaded. 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?

With an output schema present, return values need not be explained, and annotations cover the destructive/idempotent profile. The budget-restoration effect is the critical missing piece an agent would otherwise lack, making this nearly complete; only permission prerequisites or irreversibility notes are 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%; both the id and the 'Must be true to delete' confirm flag are fully documented in the schema, including the read-mode caveat. The description adds no parameter detail beyond that, 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 (delete) and resource (discount), and adds the consequential side effect that the deleted amount is returned to the project's budget. This clearly distinguishes it from sibling mutations like update_discount or delete_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 gives no guidance on when to delete versus update a discount, no prerequisites, and no mention of the confirm requirement or irreversibility. Usage is only implied by the verb 'delete'.

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds domain-specific behavioral context beyond them: deletion has the side effect of re-freeing the period's days for declarations. It stops short of stating irreversibility or the confirm requirement.

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 zero filler; the verb and resource lead and the effect follows immediately.

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 the destructive/idempotent profile, a 100%-covered schema, and an output schema for return values, the description only needs purpose and effect — both present. It could mention that 'confirm' must be true, but the schema already carries that requirement.

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

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

Schema description coverage is 100%, with both 'id' and the mandatory 'confirm' flag fully documented in the schema. The description adds no parameter-level detail, 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?

Names a specific verb ('Delete') and resource ('a leave period'), and adds the consequence that its days become available for declarations again. It is clearly distinguishable from the other delete_* siblings by resource, but it does not explicitly route against alternatives such as update_leave_period.

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 note about freeing days for declarations hints at why an agent would delete rather than update or keep the period, but there is no explicit when-to-use/when-not guidance or named alternative. Adequate but with clear gaps.

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

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

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), so the description's job is to add nuance. It does: it discloses a hard server-side refusal condition (attached declarations) and the confirm gate that governs whether anything is deleted. It doesn't discuss reversibility or what the output reports, which keeps it from a 5.

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

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

Two short sentences with no padding; the destructive action and its two gates are front-loaded. The second clause ("which is the safety net; `confirm: true` is this server's") trails off grammatically, costing a point for structure but not for length.

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

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

For a destructive, annotated mutation with a 100%-covered schema and an output schema present, the description supplies the two facts an agent most needs before invoking it: the refusal condition and the confirm requirement. Return-value detail is correctly delegated to the output schema, so 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 coverage is 100% and both parameters are already documented in the schema (including "Must be `true`. Without it nothing is deleted."). The description restates the confirm requirement with a rationale framing but adds no new syntax, accepted identifier forms, or edge cases beyond the schema. Baseline 3 applies when the schema carries the load.

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 first sentence states a specific verb and resource ("Delete a project"), which is unambiguous and cleanly distinguishable from siblings like delete_task, delete_customer, or update_project. It does not explicitly name siblings, but the verb+resource pair is concrete enough that no differentiation is needed.

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 the operative precondition: deletion is refused while declarations are attached, and `confirm: true` is required. That is real usage context about when the call will and won't succeed. It stops short of naming alternatives (e.g., detaching declarations first, or update_project), so it isn't a full when/when-not/alternative 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=true, and openWorldHint=true, so the bar is lower, yet the description still contributes real value by disclosing the downstream effect on the project's budget. It does not address whether the deletion is recoverable or what the response returns, but the budget side effect is the non-obvious behavior 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?

A single sentence with zero filler; the action and its consequence are front-loaded and nothing is repeated from the schema or annotations.

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

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

With an output schema present, return values need not be described, and annotations cover the safety and idempotency profile. The description supplies the one missing high-value fact — the budget impact — leaving only minor gaps such as reversibility of the delete.

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 'id' and the 'confirm' flag (required true to delete) are already documented in the schema. The description adds no parameter detail beyond that, which is the expected baseline when the schema carries the burden.

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

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

States a specific verb and resource ('Delete a purchase') and adds the consequence that distinguishes it from a generic delete. It does not explicitly contrast with siblings like update_purchase or get_purchase, but the purchase scoping makes the target unambiguous among the many delete_* tools.

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

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

No guidance on when to delete versus update, no prerequisites, and no mention of alternatives such as update_purchase or list_purchases. The agent must infer that this is the terminal operation for a purchase record.

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

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

Annotations already cover the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=true), so the bar is lower, and the description still contributes a non-obvious behavioral rule: deletion is blocked while declarations are attached. It does not, however, describe error behavior beyond that or the confirm guard, which lives only in the schema.

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

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

Two short sentences, front-loaded with the operation and followed by the one non-obvious constraint. 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?

An output schema exists, so return values need no explanation, and the annotations plus description cover the destructive nature and the declaration precondition. What remains thin is failure/auth context, but for a simple single-target delete this is close to 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 100%, so all three parameters including the mandatory 'confirm=true' guard and the project disambiguator are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a task'), which cleanly separates it from the create/update/get/list_task siblings. It does not explicitly differentiate itself from other delete_* tools, but the resource name makes the target 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?

Usage is implied by the operation, and the description adds a useful precondition ('refuses while declarations are attached'), which tells the agent when the call will fail. However, it names no alternatives and gives no guidance on prerequisites such as permissions or the required confirm flag.

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, but the description adds context the annotations cannot carry: the action is irreversible, Gryzzly has no undo, and the call refuses to run unless confirm is true. This is exactly the behavioral disclosure needed for a destructive mutation.

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: action, risk/gating constraint, then alternative path. The most important operational facts are front-loaded and no sentence 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 destructive, schema-backed tool with an output schema, the description covers everything an agent needs: what it does, the id source, the irreversibility and confirm requirement, and the correct sibling for corrections. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance for the id parameter ('as returned by list_time_entries') that the schema does not provide. The confirm semantics ('refuses to run without confirm true') largely restate the schema, keeping this just short of a 5.

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

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

States a specific verb and resource ('Delete one time declaration by its id') and ties the identifier to its source ('as returned by list_time_entries'). It explicitly distinguishes itself from update_time_entry, so an agent can route correctly without opening a schema.

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

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

Gives an explicit alternative with the selecting condition: 'Use update_time_entry instead to correct a duration, day, task or description.' It also sets the precondition that the person must see and agree to the deletion before calling, leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds real value beyond them by disclosing the upstream browser-session dependency and the typical API-key failure mode. It does not mention the disk side effect implied by `save_to`, which is the one behavior left dark.

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 most decision-relevant fact (it often fails without a browser session) is stated up front rather than buried. 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the critical failure mode. The remaining gap is what happens when `projects` is left null (all projects?) and the fact that `save_to` writes to the server's filesystem.

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 the format enum and the date bounds) is already documented in the schema. The description only echoes the CSV/XLSX formats, adding no syntax or default detail beyond what the schema provides — baseline 3 is appropriate.

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

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

States a specific verb and resource ("Download Gryzzly's project export") and names the output formats (CSV or XLSX), so the agent knows this produces a file rather than records. It doesn't explicitly contrast with the sibling export_times_and_leaves, but the resource name is specific enough to separate the two.

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 caveat that the endpoint "usually fails with an explanation rather than a file" when using an API key is a genuinely useful signal about when this tool will and won't succeed. However, no alternatives are named (e.g. list_projects for querying data), and there's no guidance on defaults such as what happens when `projects` is omitted.

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 and openWorldHint; the description adds the decisive behavioral fact that the endpoint requires an upstream browser session and currently fails with an explanation (not a file) under API-key auth. That auth-failure mode is exactly the kind of context annotations cannot 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?

Three sentences, front-loaded with what the tool produces, followed by the alternative-routing caveat and a one-word safety note. No filler; every sentence carries information the agent needs before invoking.

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?

An output schema exists, so return-value explanation is unnecessary; the description still covers the failure mode the output schema cannot. For a 4-param, zero-required export tool, nothing an agent needs to decide or call 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 from/to/format/save_to are already documented in the schema. The description restates the date range, format choices and save path without adding syntax, defaults beyond 'csv', or path-format detail, 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 (Download/export) and resource (declared time and leave periods) with scope (date range), output forms (CSV/XLSX), and an optional server-side save path. It is clearly distinguishable from export_projects and from list_time_entries/timesheet.

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

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

Explicitly names the preferred alternatives ('Prefer list_time_entries or timesheet for reading time') and gives the condition under which this tool is the wrong choice (API-key auth fails against the upstream browser session). This is a rare, fully actionable routing instruction.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile, so the bar is lower. The description adds the returned fields but omits notable behavior implied by the schema, such as the 'confirm' flag being ignored for reads, and offers no auth or pagination 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?

A single front-loaded sentence with zero filler; the scope ('one customer') comes first and the payoff is immediate.

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 an output schema present and annotations carrying the safety profile, the description needn't explain return values. It is essentially complete for a simple single-resource read, though it could note the ignored 'confirm' 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?

Schema description coverage is 100%, so both parameters (customer, confirm) are already fully documented in the schema. The description adds no syntax, format, or resolution detail beyond that, 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+resource ('Read one customer') and even the fields of interest (active status, manager), which cleanly separates it from list_customers and get_user. It does not name a sibling explicitly, but the singular scope makes the distinction obvious.

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?

Reading one customer implicitly contrasts with list_customers, but the description never states when to use this versus the list or get_user variants, nor any prerequisite. 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=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the result for an unknown id and the budget-offer prerequisite. It does not, however, explain the odd confirm parameter that the schema says is ignored when reading.

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

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

The description is four short sentences with no waste. It front-loads what the tool does, then adds lookup guidance, read-only behavior, and the prerequisite in a logical 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?

An output schema exists, so return values need not be documented. The description covers the required id, the read-only guarantee, not-found handling, the list_discounts lookup path, and the feature prerequisite. Nothing essential for calling this read tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description only restates that the id identifies the discount and says nothing about the confirm parameter. Baseline 3 is appropriate when the schema fully carries parameter semantics.

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

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

The description states a specific verb and resource ("Read one discount by its identifier") and enumerates the fields returned (name, amount, project/task). It clearly distinguishes this single-object read from list_discounts and from create/update/delete_discount siblings.

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

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

It explicitly routes the agent to list_discounts to obtain the id first, states the read-only nature, describes the not-found behavior for unknown ids, and names the prerequisite feature (Gryzzly's budget offer). This covers when to use the tool and the key prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the identity of the returned fields, but does not mention permissions, rate limits, or failure behavior for a missing id. With annotations carrying the main burden, this is an adequate but modest contribution.

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 economical sentence with the core action front-loaded and the returned fields listed after the colon. 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 simple one-parameter lookup with an output schema present, the description is complete: it identifies the operation, the key, and the returned fields. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the single id parameter is already fully documented in the schema. The description only restates that lookup is 'by identifier', adding no syntax, format, or example beyond the structured data. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Read one group by identifier') and names the fields returned (name, groupset, manager). It implicitly distinguishes itself from list_groups by saying 'one group', but never explicitly names a sibling as the alternative.

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: fetch a single group when you have its identifier. There is no explicit when-to-use, when-not-to-use, or pointer to a sibling like get_groupset or list_groups, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the response carries an exclusivity flag, which is return-value information the output schema likely already conveys, so it adds little behavioral context beyond the annotations.

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

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

A single well-formed sentence with the action and payload front-loaded and no wasted words.

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

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

For a simple single-parameter read with full schema coverage, annotations covering safety, and an output schema that documents returns, the description is essentially sufficient. It could name the sibling boundary explicitly to be fully self-guiding.

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 a single id parameter already documented as 'The object's identifier.' The description's 'by identifier' merely restates the schema, 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?

States a specific verb (read) and resource (one groupset) and identifies the lookup key (identifier). It implicitly contrasts with the sibling list_groupsets but never names it, so an agent still has to infer the retrieval-vs-listing boundary.

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?

'Read one groupset by identifier' implies the when: single-item lookup when you already have the id. There is no explicit statement of when to prefer it over list_groupsets or get_group, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description is consistent with those hints but adds no extra behavioral context such as permission requirements or what happens when the id does not exist (error vs empty), which matters for a fetch tool.

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, scope and payload summary are all delivered without waste.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only nature. The description is complete enough to call the tool correctly, with only error/not-found behavior left unspecified.

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 the id and the confirm parameter are fully documented in the schema itself ('Must be true to delete. Ignored when reading.'). The description's 'by identifier' merely restates the id parameter, adding 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 ('Read') and resource ('one leave period by identifier') and distinguishes itself from list_leave_periods by emphasizing the single-item, id-keyed scope. It even previews the returned content (days, half days, reason), so an agent knows exactly what it fetches.

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 phrase 'by identifier' signals this is the lookup-by-id path versus the list siblings, but there is no explicit when-to-use statement or named alternative (list_leave_periods, get_... variants). 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=true, so the 'Read-only' statement adds little. However, the description adds a genuinely useful behavioral trait not in the annotations: an ambiguous name is refused and matching candidates are returned instead of guessing, which tells the agent how to handle a failed lookup.

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

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

Three tight sentences: the core action and returned fields first, sibling routing second, behavioral caveat last. No filler, and the enumeration of returned fields is compact rather than exhaustive 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 single-read lookup tool with an output schema present, the description covers everything the agent needs: what it returns, how to disambiguate from siblings, safety profile, and ambiguity failure behavior. Return-value format is delegated correctly to the output 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 the parameter is already documented as 'by name, code or id.' The description reinforces the accepted identifier forms and adds the ambiguity-resolution behavior tied to that parameter, modestly exceeding the baseline for a fully documented single 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 ('Read one project in full') and enumerates the scope of what is returned (status, dates, visibility, contributors, managers, groups, tags, customer, note). It explicitly distinguishes itself from the sibling tools list_projects and get_project_metrics.

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 alternatives and the conditions that select them: 'Use list_projects to browse or search; use get_project_metrics for budget and time counters.' The agent can route between the three project tools without 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 and openWorldHint=true, and the description's 'Read-only' merely restates that. The one genuinely additive detail is the unit disclosure ('durations in seconds'), which the annotations do not provide. Beyond that it says nothing about permissions, missing-data behavior, or freshness of the counters.

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 tightly packed sentences: purpose and return fields first, then sibling routing, then the safety hint. No filler, and the most decision-relevant information 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?

With an output schema present, the description need not explain return values, and annotations carry the safety profile. Purpose, lookup key, and sibling disambiguation are all covered, so 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% and the single parameter is fully documented in the schema as 'The project, by name, code or id.' The description repeats that phrasing verbatim, adding no syntax, format, or ambiguity-resolution detail. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb and resource ('Read the budget and time counters of one project') and enumerates exactly what is returned: budget amount, budget spent, planned time, elapsed declared time. It also names the lookup key (name, code or id), so an agent can distinguish it from sibling getters 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?

Explicitly routes to alternatives with conditions: 'Use list_projects_metrics to compare several projects in one call, and get_project for the project's settings rather than its numbers.' Both the multi-project case and the settings-vs-numbers case are covered, leaving nothing 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 and openWorldHint=true, so the description's "Read-only" restatement adds little. What it does add is genuinely useful and not in the structured data: unknown ids surface as not-found rather than erroring, and it requires Gryzzly's budget offer — a real prerequisite/feature-gate the agent must satisfy before calling.

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 the id-lookup path, then the prerequisite. Slightly padded by enumerating return fields that an output schema (which exists) already carries, but no sentence 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?

With an output schema covering return values, annotations covering the read-only profile, and full schema coverage on both params, the description only needed to add the non-obvious bits — the list_purchases prerequisite, not-found behavior, and the budget-offer requirement. It does exactly that.

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

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

Schema description coverage is 100%, and the schema itself explains that `confirm` is only meaningful for deletion and ignored when reading — more than the description says. The description only restates that `id` identifies the purchase, adding no format or lookup 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?

Opens with a specific verb+resource ("Read one purchase by its identifier") and enumerates what is returned (name, charge-to project/task, paid and billed prices, dates, billing policy). It is immediately distinguishable from list_purchases and from sibling getters like get_project or get_discount.

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

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

Explicitly routes the agent: "Use list_purchases to find the id first," which is the key prerequisite for obtaining the required id. It does not state exclusions (e.g., when get_project_metrics or list_purchases would be preferable), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the response includes the tag's name and its owning tagset, which is mild but useful context; there is no mention of error behavior when the id is unknown.

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 zero filler; the scope and the returned fields are packed into one clause without 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 one-parameter read with full schema coverage, an output schema, and annotations covering safety, the description covers what is needed to invoke it correctly. Nothing critical is missing, though it could note the not-found case.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in the schema itself. The description's 'by identifier' merely restates the parameter rather than adding format, source, or lookup semantics, 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 tag') and scopes it to a single object via identifier, which cleanly separates it from the sibling list_tags and from get_tagset. It does not explicitly name an alternative, but the singular/plural distinction makes the role 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?

Usage is only implied: an agent can infer this is for fetching a single tag when its id is known. There is no explicit when-to-use, no guidance on when to prefer list_tags or get_tagset instead, and no stated prerequisites.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description only needs to add context. It does add one useful behavioral fact, that the result reports tag exclusivity, but says nothing about error/not-found behavior or permission requirements.

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

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

One short sentence, front-loaded with the verb and resource, with minimal waste. The trailing 'whether its tags are exclusive' clause is slightly awkward but earns its place by disclosing a return-value characteristic.

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 single-entity getter with an output schema present, the description does not need to explain return values. Combined with annotations covering safety, only minor edge-case context (not-found handling) is missing.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in the schema, so the baseline is 3. The description only echoes that lookup is by identifier, adding no format or constraint details 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 (Read) and resource (one tagset) with the lookup key (identifier), which cleanly separates it from list_tagsets and get_tag/get_tagset-adjacent tools. It does not name a sibling explicitly, which keeps it 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 singular 'one tagset by identifier' implies the single-fetch use case versus the list_tagsets bulk case, but there is no explicit when-to-use or when-not-to-use statement. Usage is inferable from naming conventions 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=true and openWorldHint=true, so the safe-read profile is covered. The description adds that the response is the full task record including budget, rate and hierarchy placement, but says nothing about missing-task behavior or permission requirements.

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

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

A single tight sentence, front-loaded with the verb and resource, with the enumerated fields earning their place by telling the agent what comes back.

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?

An output schema exists, so return values need not be re-explained, and the two parameters are fully covered by the schema. The only gap is the absence of guidance on single-vs-list retrieval, which is minor for a simple read 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 coverage is 100%, so both parameters (task, project) are already documented in the schema, including that project disambiguates a name. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (one task) and enumerates the content returned (budget, rate, planned time, hierarchy). The singular 'one task' implicitly separates it from list_tasks, though that sibling is never named explicitly.

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

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

Usage is only implied: fetch a single task's full detail. There is no statement of when to prefer this over list_tasks or get_project, and no mention of prerequisites or the name-ambiguity case that the project parameter exists to resolve.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral detail — that rates are only returned 'when the plan exposes them' — but says nothing about permissions, error cases, or the meaning of 'approved until'.

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

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

One tightly packed sentence that front-loads the verb and resource and appends the returned fields with no filler.

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

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

For a one-parameter read-only getter with an output schema present, the description covers what the agent needs; return-value documentation is provided in the schema. It stops short of routing guidance or edge-case behavior, but nothing essential to calling 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%; the single `user` parameter is already documented as accepting name, email, id, or `me`. The description 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 and resource ('Read one user') and enumerates the returned data (role, groups, approval date, rates). This distinguishes it from siblings like list_users (plural), whoami (self), and get_group (different resource) 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?

Usage is only implied by the singular 'one user' framing; the description never says when to reach for this vs list_users or whoami, nor any prerequisites. Adequate but leaves the agent to infer the alternative.

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=true, idempotentHint=false. The description adds two pieces of context the annotations cannot: that file_path resolves on the server's filesystem (an important security/location constraint) and that the report names every refused line, disclosing partial-failure semantics. Idempotency/duplicate handling remains unaddressed.

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

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

Three short sentences, front-loaded with the core action before the input-mode details. The closing sentence about refused lines is slightly awkwardly phrased but earns its place by conveying failure behavior.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain return values. It covers sources, server-side path semantics, and partial-failure reporting, leaving only cross-sibling routing and permission prerequisites uncovered.

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

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

Schema description coverage is 100% and the format is self-documenting via the ImportFormat enum, so the schema carries the burden. The description reinforces the inline-vs-path distinction but adds no syntax, format, or mutual-exclusivity rules beyond what the schema already states.

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

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

States a specific verb and resource (import leave periods) and the accepted source formats (CSV/XLSX). It does not explicitly distinguish itself from siblings like create_leave_period or list_leave_periods, but an agent can infer the bulk-import scope from the name and text.

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 explains the two input modes (inline content vs. a path on the server machine) which is genuinely useful routing guidance. However, it never says when to use this bulk importer instead of the single-record create_leave_period sibling, nor prerequisites such as required permissions.

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 openWorldHint=true, idempotentHint=false, and readOnlyHint=false. The description adds crucial behavioral context beyond annotations: Gryzzly sends the invitation and the user record exists immediately, pending acceptance. This informs the agent about state changes and the non-idempotent nature of the operation.

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

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

Two sentences with zero waste, front-loading the purpose and then the key behavioral side effect. 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?

Given that an output schema exists, annotations cover the safety profile, and schema descriptions are complete, the description supplies the needed purpose and side-effect details. It could mention permission requirements or duplicate-invite behavior, but those are minor gaps for a simple invite operation.

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

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

Schema coverage is 100%, and the description does not add any meaning beyond what the schema already documents for email, role, and group_ids. Baseline 3 is appropriate when the schema fully carries parameter semantics.

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

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

States a specific verb and resource: 'Invite someone to the team by email.' No sibling tool performs this action, so it is unambiguous. The added clause about the user existing immediately further distinguishes it from a simple notification.

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 clear context for when to use the tool: to invite someone to the team by email. There are no alternative invite tools among siblings, so no explicit comparison is needed, but it also lacks when-not-to-use guidance or prerequisites such as required permissions.

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 and openWorldHint, so the safety profile is covered; the description reinforces read-only and adds genuinely non-obvious behavior: an empty result is an empty list, not an error. It stops short of describing pagination behavior beyond what limit/offset imply.

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

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

Front-loaded with purpose, then usage routing, then filters, then error semantics. Every clause carries distinct information; no filler or repetition of the tool name.

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?

An output schema exists so return values need no explanation, and the description covers the remaining gaps: alternatives, filter scope, read-only nature, and empty-result semantics. Nothing needed to call or route this tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description summarizes the filter axes (name fragment, active status, managers by name/email/id), which mirrors rather than extends the schema — correct baseline of 3.

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

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

States a specific verb (list) plus resource (customers) and even clarifies the domain model — organisations that projects are attached to and billed for. It distinguishes itself from get_customer (single detail) and from list_projects, so an agent can separate it from siblings without opening a schema.

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

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

Gives an explicit workflow trigger ('find a customer's id or name before create_project or list_projects(customer=...)') and names the alternative for single-record retrieval ('use get_customer for one customer's detail'). When-to-use and when-not-to-use are both present.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a valuable behavioral constraint beyond annotations: every call returns no_permission without Gryzzly's budget offer. It does not describe pagination or rate limits, but those are partly covered by the schema.

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

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

The description is short and front-loads the purpose before usage, alternatives, and caveats. The standalone 'Read-only.' sentence repeats the readOnlyHint annotation and slightly reduces the otherwise efficient structure.

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

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

For a read-only list tool with a full input schema, an output schema, and annotations, the description covers purpose, sibling differentiation, permission prerequisites, and filtering behavior. Return values and pagination details are handled by the output schema and input schema respectively, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description says filters accept project and task names, codes or ids, which largely mirrors the schema descriptions and adds no new syntax or defaults beyond what is already structured.

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 discounts') and clarifies the domain object as amounts taken off a project's or task's budget. It explicitly distinguishes from the sibling get_discount and names what is returned ('their names and amounts').

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 ('audit what was granted on a project') and names the alternative ('use get_discount when you already hold one discount id'). It also states the prerequisite for any successful call ('Without Gryzzly's budget offer every call answers no_permission'), leaving little 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 and openWorldHint=true, and the description adds a genuinely useful operational fact beyond them: the upstream is read-only and groups can only be managed through the Gryzzly UI, so no create/update tool exists. It does not cover pagination behavior or result shape, but the output schema handles returns.

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 purpose is front-loaded and the read-only constraint follows immediately, so 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 zero-required-parameter list tool with a full schema and an output schema, the description is largely sufficient: identity, domain meaning, and the read-only upstream constraint are all covered. It stops short of routing the agent among the many list_* siblings, which is the 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 100% and every one of the five parameters (ids, limit, query, offset, set_ids) is documented in the schema itself. The description adds no filtering, pagination, or format detail beyond that, so the baseline 3 applies.

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

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

States a clear verb (List) and resource (groups) and adds domain meaning by explaining that groups are the user groupings to which Gryzzly assigns projects and rates. It does not, however, distinguish itself from near-siblings like list_groupsets or get_group, so an agent must infer the boundary.

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

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

The description gives no explicit when-to-use guidance, no conditions for choosing this over get_group, list_groupsets, or list_users, and no prerequisites. The only directional hint is that writes must happen in the Gryzzly interface, which is behavioral rather than usage-selection guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds real context beyond that: groupsets are managed upstream in the Gryzzly web app, so no write path exists, and an empty result is an empty list rather than an error. It stops short of describing pagination behaviour or result ordering, but the safety profile is well covered.

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

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

Three sentences, front-loaded with the definition, then usage, then behavioural constraints. Every sentence carries information the agent needs; nothing is padding.

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?

An output schema exists, so return-shape detail is not required here. The description covers the domain model, the read-only constraint, the empty-result semantics, and routing to siblings, which is everything needed to call a five-parameter list tool correctly.

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

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

Schema description coverage is 100%, so all five filters (ids, limit, query, offset, set_ids) are already documented in the schema. The description adds no filter syntax, pagination interaction, or default-value guidance, 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 ('List groupsets') and immediately defines the domain concept ('the families user groups belong to ... holds groups such as teams or sites'). It also names the sibling it is not (get_groupset for a single one), so an agent can distinguish it from list_groups and get_groupset without opening a schema.

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

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

Gives explicit sequencing advice ('use it to understand how the team is organised before reading list_groups') and points to the alternative for the single-item case ('use get_groupset for one groupset'). Both when-to-use and the alternative are spelled out rather than inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds a non-obvious domain rule not present in structured fields (the system refuses a declaration on a day already declared as leave). It does not discuss pagination behavior, though limit/offset in the schema imply it.

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: the first states what is listed and its scope, the second earns its place by explaining the concrete downstream benefit. The core action 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?

An output schema exists, so return values need not be explained, and the input schema fully documents all six optional parameters. With annotations covering the read-only/open-world profile and the description covering when-to-use and the leave-conflict rule, 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 all six parameters (to, from, week, limit, users, offset) are already documented with examples and defaults in the schema. The description adds no parameter-level syntax or format detail, 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?

States a specific verb and resource ('List leave periods') plus the scoping dimension ('over a week or a period'), which maps to the week/from/to parameters. It does not name the sibling singular lookups (get_leave_period) or the sibling list tools, so the agent must infer differentiation from the name alone.

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

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

Gives an explicit usage context tied to a sibling workflow: 'Useful before logging time,' which routes the agent to call this before log_time/log_time_bulk. No when-not guidance or explicit alternative-naming, but the when-to-use signal is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit for the cross-tool behavioral fact that the name returned here is what log_time accepts, which is not derivable from any structured field. It stops short of describing pagination behavior beyond what the schema already documents.

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, filters front-loaded, and the second sentence is a genuinely useful routing hint rather than filler. Nothing could be removed without losing information.

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

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

For a read-only, zero-required-param list tool with a full-coverage schema and an output schema, the description covers what is needed: what it lists, how it filters, and how its output is consumed downstream. Return-value detail is correctly left to the output 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% and all five parameters (limit, offset, query, status, customer) are documented there, including enum values for ProjectStatus. The description only restates the filter intent ('status, customer or a fragment of their name or code') without adding syntax, formats, or defaults 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) and resource (projects) plus the exact filter dimensions, which cleanly separates it from get_project (single fetch), list_projects_metrics (metrics) and export_projects (export). An agent can pick it out of a very crowded sibling set 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?

Provides real when-to-use context by naming the downstream workflow ('starting point for logging time') and the tool it feeds (log_time). It does not, however, state when to prefer siblings such as get_project or list_projects_metrics, so the exclusion side of the guidance is missing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: identifiers are resolved before the request and an unknown or ambiguous name aborts the entire call, listing candidates. That all-or-nothing failure mode is valuable context, though auth/rate-limit behavior is not addressed.

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 what is read, then usage, then safety, then failure behavior. The parenthetical enumerating the counters is dense but informative, and no sentence is filler.

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

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

With an output schema present, the description need not detail return values, and the annotations carry the read-only profile. It covers the remaining agent-critical unknowns: batch semantics, sibling routing, and identifier-resolution failure handling.

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

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

Schema coverage is 100% and the single 'projects' parameter already documents 'by name, code or id', so the description's restatement earns no credit. It does, however, add resolution semantics for the parameter values — that an unresolvable name fails the whole call and returns candidates — which goes 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 and resource ('Read budget and time counters'), enumerates exactly what is returned (budget amount, budget spent, planned and elapsed time), and scopes it to 'several projects in one call'. It explicitly distinguishes itself from the sibling get_project_metrics, so an agent can route 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?

Gives both a positive use case ('compare projects or build a portfolio view') and the named alternative with the condition that selects it ('use get_project_metrics for a single project'). Nothing about when to pick this over its sibling is left to inference.

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

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

Annotations already cover readOnlyHint and openWorldHint, but the description adds material the annotations cannot express: that an unknown name is an error listing what exists, and that without the Gryzzly budget offer every call returns no_permission. It does not discuss response shape or pagination behavior, which keeps it 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?

Five tight sentences, front-loaded with purpose and definition before alternatives, permissions and filter behavior. No filler and nothing that restates the title.

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?

An output schema exists, so return values need no explanation; with annotations plus output schema, the description supplies the remaining gaps an agent needs — sibling routing, permission gate, and filter error behavior. Complete for a read-only filtered list 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 coverage is 100%, so the baseline is 3; the description adds marginal value by restating that filters accept project and task names, codes or ids and by specifying the failure mode for an unknown name. It says nothing about limit/offset semantics, which the schema already documents, so it does not fully escape 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 and resource, defines what a 'purchase' is (extra costs such as licences or subcontracting), and distinguishes itself from get_purchase by contrast. An agent can tell it apart from the many sibling list_* tools without opening a schema.

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

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

Gives explicit use cases ('review what a project cost beyond time') and names the alternative plus the condition that selects it ('use get_purchase when you already hold one purchase id'). It also flags the permission prerequisite, so the agent knows when this call is even viable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds genuine value by disclosing that the read-only restriction is an upstream property and that mutation must occur in the Gryzzly interface, which the annotations do not convey.

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

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

Two short sentences, front-loaded with the core action followed by the read-only constraint. No filler, no 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?

With a dedicated output schema present, return values need not be explained, and the schema fully covers parameters. The description covers what the tool does and its read-only nature, leaving only alternative-tool routing unaddressed.

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

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

Schema description coverage is 100%, so the five parameters (ids, limit, query, offset, set_ids) are already fully documented in the schema. The description adds no filtering or pagination detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List tags') and adds scope by noting tags label projects and tasks. It does not explicitly differentiate itself from close siblings like get_tag or list_tagsets, but the plural list-noun pattern is reasonably clear.

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

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

No explicit when-to-use or when-not conditions, and no alternative sibling is named. The note that tags are managed in the Gryzzly interface implies this tool is read-only lookup, which is implied usage guidance rather than stated routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: read-only upstream too (tagsets managed in the Gryzzly web app) and the empty-result behavior ("An empty result is an empty list"). Missing pagination behavior, though offset/limit are documented in the schema.

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

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

Front-loaded with the core action and concept, then usage guidance, then behavioral notes, in a compact three-sentence block. Every clause earns its place; the parenthetical definition prevents ambiguity about what a tagset is.

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 an output schema present, return values needn't be explained, and annotations cover the safety profile. The description supplies the conceptual definition, sibling routing, upstream read-only status, and empty-result semantics, leaving nothing an agent needs 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 all five parameters (ids, limit, query, offset, set_ids) are already documented in the schema. The description adds no parameter-level detail, which is acceptable when the schema does the heavy lifting, 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+resource ("List tagsets") and immediately defines the concept ("the families tags belong to... used to label projects and tasks"). It distinguishes itself from siblings by naming both list_tags and get_tagset, so an agent can route correctly 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?

Explicit when-to-use ("Use it before list_tags to see which tag families exist") and explicit alternative ("use get_tagset for one tagset"). It also signals that tagsets are managed upstream in the web app, implying no create/update path here.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description usefully adds that container and completed tasks are filtered by default, but the claim that completed tasks are 'filtered out by default' directly conflicts with the schema's include_completed 'Defaults to true', leaving the actual default ambiguous.

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

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

Two tight sentences, front-loaded with the action and resource, with the filtering defaults following. Nothing is padded, though the second sentence could be shorter given the schema already documents both include_* flags.

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?

An output schema exists and annotations cover the safety profile, so the description need not explain return values. Combined with 100% schema coverage on all six optional parameters, the definition is sufficient to invoke the tool correctly.

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