Zenning

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

Annotations already declare readOnly=false, destructive=true, and openWorld=true, so the safety profile is known. The description adds useful operational context beyond that: asynchronous statuses, waitSeconds behavior, credit consumption, and approval handling. It does not explain permissions or exactly what 'destructive' may affect, leaving a minor gap.

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

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

Front-loads the core action and wait behavior, then adds only necessary routing and state details. Each sentence earns its place with no redundant restatement of the schema or 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?

Despite no output schema, the description explains the important return statuses and what to do for each, plus thread and workspace semantics. For a complex, asynchronous assistant tool with five parameters, this is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents message, mode, threadId, waitSeconds, and workspaceId. The description reinforces threadId continuation and waitSeconds/status behavior, but does not add syntax or format meaning beyond the schema's own 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 ('Send a message to Zenning ... and wait for its answer') and distinguishes the tool from siblings by naming get_chat_result and threadUrl as follow-up paths. An agent can tell it is the primary chat-entry tool.

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

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

Gives explicit when-to-use guidance ('anything that needs Zenning's own tools or your connected apps') and names alternatives for edge states: call get_chat_result when status is 'running', open threadUrl when status is 'needs_input'. It also clarifies new-chat vs. continued-chat behavior.

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 give readOnly/destructive/openWorld hints; the description goes further by explaining the two possible outcomes (browser sign-in link vs. a link to finish in Zenning) and the security property that credentials never pass through the chat. That is real added context beyond the structured fields, though it says nothing about idempotency or rate limits.

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

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

Three short sentences, front-loaded with the action and discovery dependency, with each sentence contributing distinct information (routing, flow outcomes, scope boundary). 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 two-parameter mutation tool with no output schema, the description covers what the tool does, where the input comes from, and what the caller receives in return (a link). Combined with annotations that establish the safety profile, 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 documented there, so the baseline of 3 applies. The description adds no syntax or format detail about 'name' or 'type' beyond what the schema already says.

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 (connect) plus resource (app), scopes it to apps surfaced by find_apps, and distinguishes itself from the sibling by naming the discovery tool. An agent can identify the tool's job without opening the schema.

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

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

The description ties usage to find_apps output and clarifies the scope boundary ('adds a connection; never edits or removes one'), which rules out misuse as an update/delete path. It stops short of naming an explicit alternative or stating prerequisites, so it is clear context without full 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 mark it as a non-read-only, open-world, destructive operation. The description adds key behavioral context beyond that: it runs asynchronously in the background, costs organisation credits, and returns a siteId for progress polling via get_site. It does not explain why destructiveHint is true, but there is no contradiction.

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

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

Three tight sentences with no filler, front-loaded with the core action and then the operational details and next step. 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 an async, credit-billed creation tool with no output schema, the description supplies the essential operational facts: background execution, billing impact, and how to track progress. It could mention error behavior or permissions, but it covers what an agent needs to invoke and follow up 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 the schema already documents all four parameters. The description does not add format, ordering, or constraint details, and the phrase 'from a description' could momentarily blur the distinction between the prompt and description fields. 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 ('Start building a new site') and frames it against a sibling ('the same as asking Zenning in chat'), so an agent can tell it apart from ask_zenning and edit_site 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?

It gives clear context for when to use this tool (to create a site from a prompt) and explicitly names the follow-up tool get_site for checking progress. It does not list exclusions or alternatives in a when-not sense, but the Zenning comparison helps.

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 flag the mutation/open-world/destructive profile; the description goes well beyond that by disclosing asynchronous background execution, credit billing to the organisation, the required edit permission, and a concurrency constraint with retry guidance. These are exactly the operational traits an agent cannot derive from structured fields.

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

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

Four short sentences, each carrying distinct information (what it does, how it runs, cost, access, retry condition). The core action is front-loaded and nothing is padded.

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

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

For an async, no-output-schema tool it covers permissions, cost, and concurrency well. The one gap is that it never says how to observe the result of the background run (e.g., via get_chat_result or a status sibling), which an agent invoking a fire-and-forget mutation would benefit from.

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

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

Schema coverage is 100% with only two documented parameters, so the schema already carries the semantics. The description adds only the indirect hint that `message` is a natural-language instruction ('the same as asking in chat'), which is marginal beyond what the schema states.

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

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

States a specific verb and resource (change an existing site) and frames it as the programmatic equivalent of a chat request. This clearly separates it from create_site, get_site, and list_sites without the agent needing to open 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 real preconditions: edit access is required, and if a build is already running the agent should wait and retry. It implies use for modifications to existing sites rather than creation, but never explicitly names create_site or ask_zenning as the alternative path, so routing is left partly 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 the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the bar is lower. The description adds genuine value by disclosing the return shape: each result reports how the app connects and whether it is already connected, which the agent needs to decide its next call.

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 action and resource, then result contents, then the follow-up call. Every sentence earns its place 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?

There is no output schema, so the description carries the burden of describing results, and it does so adequately (connection method + connection status). Minor gaps remain: no mention of result ordering, pagination, or behavior when the query matches nothing.

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 (query, limit with default 10 and max 25) are fully documented in the schema, so baseline is 3. The description only reinforces that query is by app name and hints at a returned 'type' field, adding no syntax or format detail 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 (Search) plus resource (apps Zenning can connect) and scopes it with 'by name'. This is clearly distinguishable from sibling list_apps (which presumably lists already-connected apps) because the description frames results as candidates plus connection status.

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

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

Provides explicit forward routing: 'To connect one, pass its type to connect_app,' which tells the agent the follow-up action and required argument. It does not explicitly contrast with list_apps or state when a search is preferred over browsing, so it falls 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, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context by enumerating the returned fields (identity, org, credit balance, spaces), which matters because there is no output 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 with zero waste: the first front-loads what is returned, the second front-loads the imperative usage cue. 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?

With no parameters and no output schema, the description carries the burden of describing return content, and it does so by listing the four payload categories. A bit more on the spaces/organisation structure would make it fully complete.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No parameter semantics are needed or missing.

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 the specific resource and enumerates what it returns: signed-in identity, organisation, credit balance, and usable spaces. This clearly distinguishes it from data-fetching siblings like get_site or get_home, though it never explicitly contrasts against them.

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

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

"Call this first to confirm the account" gives explicit sequencing guidance that an agent can act on. It stops short of naming when-not-to-use or a specific alternative, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is free to add the genuinely useful trait: the call blocks and waits up to waitSeconds for the run to finish, and the result mirrors ask_zenning's shape. It does not say what happens if the run is still unfinished when the wait expires.

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, zero filler, front-loaded with the two use cases before the timing and return-shape details. Every sentence carries information the agent needs.

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?

All three parameters are documented and the return shape is anchored by reference to ask_zenning, which compensates for the absent output schema. The one real gap is timeout/partial-result behavior, which matters for a polling tool.

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

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

Schema description coverage is 100%, so runId's origin ('from ask_zenning'), the threadId, and the 0-240 waitSeconds range are already fully documented in the schema. The description adds no syntax or semantics beyond that baseline.

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

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

Names a specific action on a specific resource ('check on a chat', 'read the latest answer') and ties the tool to ask_zenning via the runId lineage. It is clearly distinct from the launch tool ask_zenning, though it never explicitly contrasts itself with the read_thread sibling that also reads chat content.

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 two concrete triggering conditions: polling a chat that 'was still working' and fetching the latest answer. It stops short of naming an alternative (e.g. read_thread) or stating when-not-to-use, so the routing guidance is clear but not exhaustive.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that omitting runId returns the latest run — but says nothing about what happens for a non-existent run or an in-progress run.

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

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

Two short sentences with the core purpose front-loaded and zero filler. Slightly terse for a tool with no output schema, but nothing is wasted.

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

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

There is no output schema, so the description bears some burden for the return shape; 'status and result' gestures at it but does not enumerate fields or possible status values. Adequate for a simple two-parameter read, but the agent is left guessing at the response.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the 'omit for the latest run' semantics. The description restates that one point and adds nothing about formats or constraints, 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?

The description names the specific resource (an AI employee run) and what is retrieved (status and result), which is enough to separate it from list_employees and run_employee. It is phrased as a noun fragment rather than a verb+resource statement, but the intent is unambiguous.

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

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

It explains the runId-omitted case, which is real usage guidance, and the schema links runId back to run_employee, implying get_employee_run is the polling counterpart to run_employee. However, it never explicitly says when to call this versus list_employees or how it relates to a still-running job.

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, non-destructive, and non-open-world, so the safety profile is covered. The description adds meaningful context beyond them: it reads the stored page rather than triggering a build, and it explains that returned items carry ids usable in other tools.

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 resource definition before the follow-up routing. Every sentence carries distinct information: content, id handoff, prompt execution, and the no-build constraint.

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

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

With no output schema, the description usefully characterizes what comes back (sections of suggestions, attention items, drafts, staged work, each with an id) and how to act on it. Nothing needed to call it correctly appears to be 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% and the enum of 14 sections is fully documented in the schema, so the schema carries the burden. The description adds no syntax or formatting guidance for limit or section, which matches the baseline 3 for high-coverage schemas.

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 ('What is on the person's Home page') and enumerates the content classes (suggestions, attention items, drafts, staged work), which distinguishes it from the sibling list/get tools. It also explicitly names the follow-up tools update_home_item and ask_zenning.

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 routing: item ids go to update_home_item for done/dismiss/snooze/restore, and suggested prompts go to ask_zenning. It also states a negative condition ('does not start a build'), so the agent knows what this call will not do.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the payload (status, live URL, access, builder reply) and implying a polling/eventual-consistency pattern with 'check progress' — a meaningful behavioral hint absent from 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?

Two sentences, no filler. The returned-fields clause comes first and the workflow trigger second, so the agent gets the essential information 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?

There is no output schema, so the description carries the burden of describing returns, and it does so adequately by naming the four response facets. It is slightly thin on failure behavior (invalid or unknown siteId) and on how frequently to poll for the builder reply.

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

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

With 100% schema description coverage and only a single siteId parameter fully documented in the schema, the baseline is 3. The description adds no format, source, or acquisition guidance for the id 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 resource (one site) and enumerates the returned facets: status, live URL, access, and the builder's latest reply. The singular 'one site' implicitly contrasts with list_sites, though no sibling is named outright.

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 to call this after create_site or edit_site to check progress, which names the triggering siblings and the workflow context. It stops short of stating when not to use it (e.g., bulk inspection, which would be list_sites).

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

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

Annotations already declare this a safe, non-destructive, non-open-world read, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the result (name, type, status), which matters because there is no output schema; it does not mention volume, pagination, or permission scoping.

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, the inventory scope front-loaded and the routing hint second. Nothing is repeated from the title or 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 zero parameters, no output schema, and annotations covering safety, the description supplies the one thing missing from structured data: what the listing contains. Only the absence of any note on how many apps come back or whether extra filtering exists keeps it short of full completeness.

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

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

The tool takes no parameters, so the schema has nothing to explain and the description is not required to add parameter meaning. Baseline of 4 applies.

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

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

The description states the resource ('the apps connected to your organisation that you can use') and the returned fields, which pins down the tool as a connected-apps inventory. It is distinguishable from ask_zenning, but it never contrasts with the sibling find_apps, leaving one plausible confusable sibling unaddressed.

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 acting-in-an-app work to ask_zenning, giving a clear when-not condition. It stops short of saying when to use this versus find_apps, so the browsing-vs-discovering choice is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and a closed domain, so safety is covered. The description adds genuine behavioral value by disclosing the returned fields (status) and, importantly, that IDs are cross-tool handles for run_employee and get_employee_run. Return format and ordering are not described, but that is minor given no output schema and no parameters.

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

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

Two short sentences, no waste: the first states what comes back, the second states what to do with it. What the tool returns is front-loaded ahead of the follow-up routing advice.

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

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

With no parameters and no output schema, an agent needs only to know what the list contains and how the returned IDs are consumed. The description supplies both, plus the fact that status is included, so 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. The description correctly implies the call is unfiltered within the caller's organisation.

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 resource precisely ('The AI employees you can use in your organisation, with their status') and implicitly distinguishes itself from run_employee and get_employee_run, which it names as consumers of its output IDs. It lacks an explicit listing verb ('list all'), but the resource and scope are unambiguous.

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

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

It gives clear forward guidance: take an id from this result and pass it to run_employee or get_employee_run. That establishes the discovery-then-act workflow and implicitly tells the agent to call this first. It stops short of stating when not to use it or how it relates to other list_* siblings.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is additive. It does add value: the visibility scoping ('sites you can see') and, importantly given there is no output schema, the shape of the return (status and live URL). It does not discuss pagination behaviour despite a limit cap of 50.

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

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

Two short sentences, no filler. The purpose and scope come first and the chaining instruction second, which is the correct front-loading order for an agent scanning for a list tool.

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

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

For a two-optional-parameter list tool with no output schema, the description covers scope, returned fields and downstream usage, which is enough to call it correctly. The only gap is pagination/limit behaviour, which is partially mitigated by the schema's own limit documentation.

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 limit (default 20, max 50) and search (name substring) are fully documented in the schema. The description adds no further parameter semantics such as sort order or case-sensitivity of search, 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 action (listing sites) with an explicit scope qualifier ('you can see in your organisation') and names the return content (status and live URL). It also distinguishes itself from get_site, edit_site and create_site by positioning itself as the source of ids those tools consume.

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 second sentence gives concrete routing guidance: take an id from here and pass it to get_site, edit_site or create_site. That is a clear, actionable workflow hook. It stops short of the 5 bar because it never states when NOT to use this tool (e.g. when to prefer search-based or filtered listing).

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds ordering ('most recently updated first') and that results are scoped to the caller's own chats, which is genuine added context, but says nothing about pagination, totals, or what an empty result means.

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

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

Two short sentences with zero filler; the scope and ordering are front-loaded and the second sentence is pure actionable routing information about the returned threadId.

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

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

With no output schema, the description usefully names the key returned field (threadId) and the sort order, which is what an agent needs to chain calls. It omits return shape details such as titles, counts, or pagination behavior, leaving a small gap for a 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 description coverage is 100%, so both parameters (limit 1-50 default 20, workspaceId) are already fully documented in the schema. The description adds no syntax or defaulting detail beyond that, which is the expected baseline 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?

Names the resource (chats/threads), the scope (your recent chats in this organisation), and the ordering (most recently updated first). It also links the returned threadId to the sibling tools ask_zenning and read_thread, so an agent can place it in the workflow, though the listing verb itself is only implied.

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 positions this as the discovery step whose threadId feeds ask_zenning or read_thread, which gives clear context for when to reach for it. It does not state when not to use it or name an alternative listing tool, 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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only that the returned id feeds ask_zenning as workspaceId; it says nothing about ordering, pagination, or whether empty results are possible, so the added behavioral value is modest.

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

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

Two short sentences with no filler; the identification of the resource comes first and the downstream usage hint second. The opening is a verbless fragment, a minor stylistic ding, but nothing is wasted.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies what an agent needs: what is listed, the workspace/space synonym, and how the result is consumed. Return shape details are unnecessary here.

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

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

The tool takes zero parameters, so the baseline is 4. The description does usefully bridge the naming gap by specifying that a 'space id' is passed as 'workspaceId' to ask_zenning, which helps the agent wire the output into the sibling call.

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

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

The description names the resource ('spaces (workspaces) you can use in your organisation') and disambiguates the workspace/space terminology, which the tool name alone would not. It is clear what is returned, though it never uses an explicit verb like 'list', leaning on the tool name for that.

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 concrete downstream guidance: 'Pass a space id as workspaceId to ask_zenning to start a chat there,' which tells the agent why it would call this tool and what to do with the result. There is no explicit when-not-to-use or alternative listed, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real behavior the annotations cannot: output is text only, and long messages are truncated. That truncation warning is exactly the kind of context an agent needs before relying on the payload.

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

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

Two short sentences, both earning their place, with the core behavior stated first and the prerequisite follow-up second. No filler, no repetition of schema or annotation data.

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

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

With no output schema, the description carries the return-value burden and does so adequately by describing content type and truncation. It leaves pagination and how to retrieve older or full messages unstated, but for a two-parameter read tool this is close to complete.

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

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

Schema description coverage is 100%, so limit and threadId are already fully documented with ranges and defaults. The description only restates where threadId comes from and 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?

Names a specific resource (the most recent messages of one chat) and scopes it precisely, so an agent can distinguish it from list_threads. The phrasing is a noun fragment rather than a verb+resource, which slightly weakens it, but the intent is unmistakable.

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

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

Gives a concrete prerequisite workflow: 'Use list_threads to find the threadId,' which directly tells the agent how to satisfy the single required parameter. It offers no exclusion guidance versus neighbors like get_chat_result, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description goes further by disclosing asynchronous background execution, credit billing to the organization, and the owner/editor auth requirement. The one gap is that it never explains why the operation is flagged destructive (what gets consumed or changed), but the billing and permission disclosures are meaningful value beyond the annotations.

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

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

Three tight sentences, front-loaded with the action and its UI analogue, then side effects (billing/access), then return behavior. No filler and each sentence carries distinct information.

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

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

Although there is no output schema, the description covers return semantics (runId may not be available immediately; poll get_employee_run as fallback), the async nature, cost, and permission requirements. Nothing an agent needs to invoke and follow up 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 both parameters are already documented in the schema; the description adds only that employeeId can be reused with get_employee_run. It says nothing about the optional 'input' test payload beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Start an AI employee's Run now') and anchors it to a concrete UI equivalent (the Run button in Zenning), so the agent immediately knows this is a trigger/execution tool rather than a read or config tool. It is also clearly distinguished from the nearby sibling get_employee_run, which is named as the status-check counterpart.

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

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

Explicitly names the alternative and the condition that selects it: call this to kick off a run, 'otherwise call get_employee_run with the employeeId to see the latest run.' Preconditions (owner or editor access) are stated up front, so an agent can judge eligibility before invoking.

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 it as non-read-only and non-destructive, so the bar is lowered, yet the description still adds real behavior: snooze is temporary and the item returns after N days, and restore reverses a done or dismissed state. That reversibility/temporality detail is not in the annotations. It doesn't say what happens to the item on dismiss long-term or how errors surface, so it isn't exhaustive.

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

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

One front-loaded sentence with no filler; the verb and source resource lead. The inline parenthetical glosses make it dense, but each clause carries information needed to pick an action value.

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

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

With no output schema needed and annotations covering the safety profile, the description adequately covers all three parameters and all four action semantics. It omits any statement of reversibility beyond restore or failure behavior, leaving minor gaps for a mutation tool.

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

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

Schema coverage is 100% (baseline 3), but the description adds meaning the schema lacks by glossing each enum value rather than just listing it ('snooze (hide it for some days, then it returns)', 'restore (move a done or dismissed item back)'). It adds nothing about itemId or the snoozeDays 1-30 bound, which the schema already covers, so it's above baseline but not maximal.

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 ('update home item') and names the source tool ('an item from get_home'), then enumerates the exact action space. An agent can distinguish this mutation tool from the read-only get_home sibling 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 clear per-action context for when each value applies (done = finished, dismiss = not wanted, snooze = hide temporarily, restore = undo a done/dismissed item), which effectively routes the agent. It stops short of explicit exclusions or prerequisites (e.g. that the item must come from get_home), so it doesn't reach a 5.

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