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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states 'Nothing is fetched,' implying no data access or side effects, and explains what the tool returns. It could go further on edge cases like what triggers 'allowed-with-alert,' but it is transparent about the core behavior.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then gives return details and a concrete usage pattern. Every sentence earns its place.

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

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

For a tool with no output schema and no annotations, the description covers the essential context: purpose, side effects, return values, and how to invoke it. The optional entities parameter is fully documented in the schema, so no critical information 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 input schema already documents both parameters thoroughly. The description reinforces the idea of passing tool calls in order and translating a request into calls, but it adds limited new parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: ask whether a sequence of tool calls would be allowed, before running any of them. It also names the return values (decision, rule, clause, remediation), which makes the tool's function unmistakable and distinguishes it from sibling tools like aggrete__scenarios.

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

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

The description clearly says when to use it: before running any tool calls, and to answer 'can I do X?' questions by translating the request into tool calls. It lacks explicit when-not-to-use guidance or named alternatives, but the usage context is strong.

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

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

With no annotations, the description carries the disclosure burden. 'List' signals a non-mutating read operation and 'Takes no arguments' confirms the call shape; the enumerated policy topics tell the agent what kind of content to expect. It doesn't state auth requirements or output formatting, but for a no-argument scenario listing these are minor omissions.

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-load the action, then give the key decision types, the no-argument contract, and the audience guidance. Every sentence adds value and there is no redundant 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?

For a simple zero-parameter tool with no output schema, this is complete: it says what is returned, what topics are covered, and when to start. There is no missing input/output information that would prevent a correct call.

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

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

The schema has zero parameters and 100% coverage, so baseline is 4. The description reinforces this with 'Takes no arguments', which prevents an agent from inventing parameters. No parameter-level detail is needed.

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 identifies the action ('List concrete things to try') and the resource ('here', i.e. the demo scenarios), and enumerates the specific policy topics covered, so an agent can tell what the tool returns. It doesn't explicitly contrast itself with sibling tools like hr__start_here, though its content is distinct.

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?

'Start here if you are new' is an explicit usage context, and 'Takes no arguments' tells the agent no parameters are needed. It doesn't mention when not to use it or name alternatives, but for a demo entry point that is a clear enough trigger.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It states that the tool writes to the outside world, is classified as egress, and can be blocked by the prompt-injection shield. It does not detail visibility, persistence, or return behavior, but for a simple post tool these are secondary.

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

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

Two sentences with no wasted text. The purpose is front-loaded in the first sentence and the egress policy earns the second sentence.

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

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

For a one-parameter tool with no output schema, this is nearly complete: it defines the action, target, side effect, and an important refusal condition. The only missing piece is any indication of what the tool returns or how success is reported, which is a minor gap.

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

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

Schema coverage is 100% and the schema already says 'text' is 'The note text to post'. The description adds no additional parameter constraints, format details, or examples, so the baseline 3 applies.

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

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

The description uses a specific verb ('Post') with a specific resource ('a note to the shared team space'), and the shared-notes context makes its write purpose clear next to siblings like corp__read_public_post. No ambiguity about what the tool does.

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

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

It gives clear context for when to use the tool—posting a note to the shared team space—and an explicit when-not: it is refused if the session has already read untrusted content. It does not name an alternative tool to use in that case, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so exceptionally well. It reveals that content is untrusted and capable of carrying prompt-injection-style instructions, and it discloses the side effect that reading triggers Aggrete's refusal of later data-sending tools (COC-SEC-002). This is critical behavioral information beyond the schema.

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

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

The description is compact and front-loaded: it opens with the untrusted-web marker and the core action, then delivers the essential security caveat. Every sentence adds value with no filler or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description provides sufficient context to call it correctly: what it fetches, that the content is untrusted, and the consequential session-level egress restriction. This is complete for an agent to understand both the action and its implications.

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 'url' parameter is already well described as 'URL of the public page or post to read.' The description adds context that the tool fetches text and that content is untrusted, but it does not need to add much parameter-level detail. 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 ('Fetch') and resource ('text of a public web page or forum post'), making the tool's function immediately clear. The '[untrusted-web]' prefix and the security caveat further distinguish it from the unrelated HR, finance, and operations siblings.

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

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

The description clearly indicates this tool is for reading public web content and provides important context about untrusted content and the session-level data egress restriction. It does not explicitly name alternative tools, but the sibling list contains no other web-fetch tool, so the context is sufficient for an agent to select it appropriately.

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

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

With no annotations, the description carries the behavioral burden. It discloses a non-obvious rule: Aggrete enforces a code-of-conduct constraint that refuses combining budget records with HR records to profile individuals. It also states what data is included in the result. It does not explicitly say the operation is read-only or describe error behavior, but for a simple lookup this is adequate.

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

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

Two sentences with no wasted words. The first sentence front-loads the core purpose and output fields; the second delivers an important constraint. The structure is compact and easy to scan.

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

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

For a single-parameter list tool with no output schema, the description gives enough information: what the result contains, the role-level detail, and a notable usage restriction. The absence of a mention of return shape or unknown-team behavior is minor given the low complexity.

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 'team' parameter is already documented with examples in the schema. The description adds only the general context of 'one team, per role,' which does not materially enrich parameter semantics beyond the schema. Baseline 3 applies.

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

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

The description clearly identifies the resource — budget lines for one team per role — and names the key fields returned (backfill-only flag, role owner email). It does not use an explicit verb like 'list' or 'get', and it does not clearly differentiate from the sibling finance__headcount_plan, so it stops short of a 5.

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

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

The description gives clear context: the tool reports budget lines for one team, per role. It also provides an explicit when-not-to-use instruction: Aggrete refuses combining these records with HR personnel records for individual profiling, which is relevant to the hr__ sibling tools. It could be stronger by naming which tool to use instead of this one in other finance scenarios.

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

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

No annotations are provided, so the description carries the burden. It discloses the key behavioral traits upfront: results are totals only, never individual people, and the scope is exactly one team. It does not cover error handling or data freshness, but for a read-only aggregate tool the main privacy and aggregation behaviors are disclosed.

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: the first states function and core constraint, the second gives a user-oriented purpose. There is no filler, and the most important facts are 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?

The tool is simple with one required parameter and no nested objects, and the description covers scope, output nature, and intended use. It lacks an output schema and does not spell out behavior for unknown team names, so it is complete but not exhaustive.

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

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

The input schema covers the only parameter, team, at 100% with a clear description and examples ('platform', 'sre', 'sales-emea'). The tool description adds no parameter-level detail beyond restating 'one team', so the baseline 3 is appropriate.

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

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

The description opens with the specific verb 'Aggregate' and a clear resource: headcount plan for one team, enumerating approved, filled, and open role counts. It also clarifies scope with 'one team' and 'Returns totals only, never individual people.' It stops short of a 5 because it does not explicitly differentiate from the sibling finance__budget_roles.

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 states a concrete use case: 'Use it to see how many roles a team is budgeted for and how many are still open.' This is clear contextual guidance, but it does not name alternatives like finance__budget_roles or state when not to use the tool, so it earns 4 rather than 5.

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

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

With no annotations, the description carries the full behavioral burden and does so well by disclosing that small categories resolve to individual pay and are refused under policy COC-HR-031. This reveals an important failure behavior and privacy constraint that an agent would not otherwise 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?

The description is three short sentences with no filler. The purpose is front-loaded, and the constraint is stated efficiently with a policy reference rather than unnecessary explanation.

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

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

For a one-parameter tool with no annotations, the description provides the core purpose, the key boundary condition, and a refusal behavior. It does not describe the exact return format or currency, but the meaning of 'average pay' is clear enough to make a correct call.

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

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

The schema already documents the single 'category' parameter at 100% coverage, so the baseline is 3. The description adds real value by defining the ten-person threshold and clarifying that broad categories are appropriate, which helps the agent choose a safe input value.

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

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

The description opens with 'Average pay for a category of workers', which names the specific operation, resource, and scope. It also clearly distinguishes this tool from the sibling tools, which cover on-call, timecards, posts, budget roles, and headcount planning rather than pay aggregation.

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 concrete guidance on when the tool can and cannot be used: categories with fewer than ten people are refused, while broad categories such as job family or location are acceptable. It does not name alternative tools, but the when/when-not guidance is explicit enough for the simple parameter set.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose a notable behavior: Aggrete redacts the email from the result before it reaches the model. This goes beyond the basic purpose and gives the agent useful expectations about output privacy.

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, front-loaded with the core purpose, and the demo redaction note is the only extra information. Every sentence adds value and there is no wasted text.

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

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

For a simple single-parameter lookup with no output schema, the description plus schema is adequate: purpose, input, and a relevant behavioral note are all present. It does not detail error cases or exact response structure, but those are not essential for this tool's simplicity.

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 email parameter already has a clear description with an example. The tool description adds 'by email' but does not materially improve on the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Look up') and a specific resource ('remaining leave and absence balance') scoped to one person by email. This clearly distinguishes the tool from sibling tools like hr__recent_joiners, which operate on groups or lists.

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

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

The description clearly indicates this is for a single-person lookup identified by email, which provides enough context to avoid confusion with the sibling HR tools. It does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that this is a listing operation and names the returned fields, which is useful. It does not mention ordering, pagination, whether 'joined' refers to team membership vs hire date, or any access/authorization considerations.

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 primary action and resource are front-loaded, and the use-case sentence earns its place by guiding selection.

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

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

For a simple read-only list tool with two parameters and no output schema, the description is largely sufficient: it states inputs, purpose, and expected output fields. It could be slightly more complete by clarifying edge cases around the time window or result ordering, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples and constraints. The description mostly restates the time-window concept ('within the last N months') and does not add significant new meaning beyond the schema.

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

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

The description uses a specific verb ('List') and resource ('people who joined a team within the last N months'), and clarifies the returned fields: email, employee id, and start date. It is clearly distinct from sibling tools by topic, though it does not explicitly contrast itself with any sibling.

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 states a clear use case: 'Use it to find recent hires on a team.' This gives an agent a direct trigger condition for selecting the tool. It does not, however, list exclusions or explicitly contrast with nearby HR tools like hr__start_here or hr__leave_balance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states the tool 'takes no arguments' and describes its behavior as explaining and pointing, implying a read-only informational action. It does not discuss side effects or output format, but for such a simple tool this is adequate.

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

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

The description is extremely concise: three short phrases, each earning its place. 'Start here' is front-loaded, followed by the tool's purpose and argument clarification. There is no filler or redundant information.

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

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

For a zero-argument, no-output-schema orientation tool, this description is complete. It tells the agent what the tool does, that it requires no arguments, and how it guides the user. Nothing essential is missing for invoking 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?

The schema already shows zero properties, but the description reinforces this by explicitly stating 'Takes no arguments.' Since there are no parameters, the description adds the needed semantic confirmation beyond the schema, warranting the baseline 4 for zero-parameter tools.

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

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

The description states a clear purpose: it is an entry point that 'Explains what this demo is and points you at the guided menu.' This uses a specific verb/resource combination and clearly distinguishes the tool from the sibling HR, finance, ops, and corp tools, which are all operational rather than orientation 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?

'Start here' is an explicit directive to invoke this tool first, which is strong usage guidance for an entry-point tool. It does not name alternatives or specify when not to use it, but given the tool's simple orientation role and zero arguments, the guidance is sufficient.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses an important non-obvious guardrail: attempting to place your own timecard next to a colleague's for comparison is refused under COC-HR-021, while team review is allowed. This gives the agent actionable policy context beyond the schema.

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

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

The description is two concise sentences with no wasted words. It front-loads the core operation and then adds the necessary policy exception. The category tag and policy code convey extra context efficiently.

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 tool with no output schema, the description gives the input scope (one person by email), the output semantics (hours per week this month), and the key access restriction. Nothing essential is missing for an agent to call it correctly.

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

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

The single email parameter has 100% schema description coverage, so the schema already documents its meaning. The description only repeats 'by email' without adding new format, default, or usage detail. The schema's own example ('your own or a colleague's') is more informative than the description's mention.

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

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

The description names a specific resource ('timecard for one person by email') and the exact output ('hours logged per week this month'). This clearly distinguishes it from sibling HR tools like leave balance or recent joiners. The [timesheets] prefix adds useful category context.

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

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

The first clause states when to use the tool: to read one person's timecard by email. The demo caveat explicitly marks a refused use case (comparing your own card with a colleague's) and an allowed one (reviewing your team's cards). It does not name an alternative tool, but no sibling appears to cover this exact function.

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

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

No annotations are provided, so the description carries the responsibility for behavioral disclosure. 'Draft' and 'propose' signal a non-committal, generated rotation rather than a final schedule, and the output content is stated. However, it does not disclose side effects, persistence, permissions, or whether anything is actually written to the rota.

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

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

The description is two short sentences with no filler; the core action and scope are front-loaded in the first sentence. The second sentence clarifies the intended use without repeating the schema. It is efficient and scannable.

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

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

For a two-parameter tool, the schema covers the inputs and the description covers the output format (weekly shifts with the assigned person's email). No output schema exists, but an agent receives enough to invoke it correctly. It would benefit from stating what happens when no person is available, but that is a marginal 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?

Both parameters are fully documented in the schema with format constraints and examples, so the schema does the heavy lifting. The description reinforces that team and quarter are the scope, but adds no parameter-level meaning beyond that. A baseline of 3 is appropriate given 100% schema coverage.

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

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

The description opens with the specific action 'Draft an on-call rotation' and immediately scopes it to 'one team and quarter.' It adds output detail—'one shift per week with the assigned person's email'—which makes the tool's purpose concrete. No sibling tool covers this domain, so it is distinguishable from the listed HR/finance 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?

It explicitly tells the agent to use the tool 'to propose who is on call, week by week,' which establishes the primary use case. It also constrains use to a single team and quarter. There are no alternative on-call siblings, so no exclusion condition is needed.

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