Conecto Calendar

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

The description goes far beyond the annotations: a held call answers approval_required with an approval_id, must be re-called once with identical arguments, and can be answered via X-Conecto-Approval or _meta.approvalId. It also discloses that the calling person never approves, that each approver gets a personal link, the two_people_over escalation, bill-specific behavior for purchasing_create_bill and purchasing_pay_bill, and the $0.001-per-call cost with no charge on failure.

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

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

The core purpose is front-loaded, but the prose is a run-on with heavy parentheticals, duplicated pricing ('$0.001.' followed by 'Costs $0.001 per call'), and a tangential sentence about rule removal ownership. Some sentences earn their place, but trimming and restructuring would materially improve readability.

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

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

For a 9-parameter tool with no output schema, the description covers the creation-to-approval lifecycle, approval mechanisms, cost, and removal conditions. It leaves two gaps: it does not say what a successful rule creation returns (e.g., a rule identifier), and it does not state who is permitted to create a rule.

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 78%, and the description supplements it with examples that clarify how 'over' and 'values' are evaluated (amount over 500; method equal to one of several verbs) and that argument may be 'total' for bills. It also explains that the approver can be an email, saved channel, or team, adding meaning for approver_email and approver_channel even though the schema text already covers most parameters.

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: it makes a named tool's calls wait for a person, with three distinct modes (all calls, calls over a threshold, calls matching listed values). An agent can tell what the tool does, though the opening sentence is syntactically tangled and it never names the sibling account_list_approval_rules it complements.

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?

Concrete scenarios are supplied (invoices_create_credit_note when amount is over 500; connect_call when method is POST/PUT/PATCH/DELETE) that illustrate when a rule applies, and the post-hold approval flow is described. However, there is no explicit statement of when to call this tool versus account_list_approval_rules or when not to create a rule, so the usage guidance is implied rather than directive.

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?

Goes well beyond the annotations (which only say non-read-only, idempotent, non-destructive): it discloses billing reassignment ('responses ... charged to that team from now on'), that rentals move with the parent, an auth/key restriction, and per-call cost with failure refund. This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the core action and resource list, and every clause carries information. It is docked slightly for the redundant cost sentence – '$0.001. Costs $0.001 per call' repeats the price twice.

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 covers side effects, auth, cost, and the failure case ('nothing if it fails'), which is most of what an agent needs. What is missing is any statement of what a successful response contains, so an agent must infer that from the idempotent/non-destructive annotations.

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

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

Schema coverage is 33% (only `id` documented). The description enumerates the accepted `kind` values, but that duplicates the enum already in the schema and adds no format/syntax detail. The required `team` parameter gets only the implicit 'to a team' phrasing, so the description does not fully compensate for the coverage gap.

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

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

States a specific verb ('move ... to a team') plus an exhaustive list of the resource kinds affected, so the agent knows exactly what domain this operates on. It is clearly distinct from siblings like account_save_team or account_pause_team.

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 a real precondition ('Only a key of the company-wide team without limits moves things between teams') and covers the bot-owned edge case ('Something a bot makes already belongs to the bot's team'). It does not explicitly name an alternative tool or a when-not-to-use case, keeping it just below 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 readOnly/idempotent/non-destructive, yet the description still adds real behavior: newest-first ordering, the fact that hash-chain verification 'breaks where an entry was changed or removed', and that the call is free. It stops short of describing pagination/cursor behavior or what an entry looks like, so not a full 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 dense sentences: the first front-loads scope and the enumeration, the second carries the sibling pointer and the verify semantics plus the cost note. No filler, no repetition of 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?

For a 4-param, no-output-schema read tool, this covers scope, ordering, the security-relevant `verify` mode, cost, and the competing tool. Remaining gaps are the two undocumented filters (`since`, `limit`) and any hint about entry shape, but nothing blocking an agent from calling it correctly.

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

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

Schema coverage is only 25% (only `action` is documented in-schema), so the description has to compensate. It does explain `verify` semantics well and effectively hints at `action` prefixes by listing event categories, but `limit` and `since` get no treatment at all — no guidance on time-window format or default/max behavior.

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 precisely (the account's admin and security actions) and enumerates the concrete event classes captured: key creation/revocation, limits and auto-reload, owner sign-ins, connectors, exports, vault reads/writes, credential changes, deletions. This is specific enough that an agent can distinguish it from account_events and account_list_calls 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 the alternative: 'Ordinary work is in the call log (account_list_calls)', telling the agent exactly when to pick the sibling instead. It also gives a conditional usage rule for a parameter ('verify: true also checks the hash chain'), which is when-to-use guidance at the argument level.

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 state readOnly, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond annotations: the call is free, and AI visibility and phone usage depend on purchased credit. It does not cover auth or rate limits, so it is strong but not exhaustive.

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

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

A single sentence front-loads the resource and then enumerates relevant returned fields; every clause is meaningful. The sentence is dense and slightly convoluted, 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?

No output schema exists, so the description must explain return values; it enumerates balance components, holds, daily budget, auto-reload state, and free reads/downloads used. With annotations covering safety and zero parameters, this is complete for the tool.

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

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

This tool has zero parameters, so there are no parameter semantics to document. The baseline for 0 params 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 resource (account balance) and enumerates the specific fields returned, so an agent knows this is a balance/credit-status read. It does not explicitly contrast with account_dashboard_link or other account_* siblings, so it is clear but not fully differentiated.

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

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

No when-to-use, when-not-to-use, or alternative guidance is provided. The word "Free" hints at cost but does not say when to call this instead of sibling account tools.

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

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

Annotations only cover read-only/idempotent/no-destruction; the description adds substantial context beyond them: the link is single-use, expires in an hour, an unopened link dies after 7 days, and the page is scoped to what 'this key' may see. Those are exactly the behavioral traits an agent needs before generating a shareable artifact.

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 idea (one-time link to a snapshot of one area) and every sentence carries usable information about usage or lifecycle. The prose is conversational and slightly padded, but not wasteful enough to drop below 4.

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 does cover the essential return semantics (a link URL that opens once) and its expiry behavior. The remaining gap is the `area` enum meaning, which is the one thing an agent must get right to call it.

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

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

Schema description coverage is 0% for the single required `area` parameter, and the description never explains that it selects among the ~51 product areas. The recruiter/bookkeeper examples loosely gesture at area selection but do not document the enum values or how to pick one. Marginal value over the schema's bare enum.

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

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

The description clearly states the verb+resource: it produces a one-time link to a page showing one area's current state. An agent can distinguish it from data-reading siblings because it explicitly says the link is a snapshot view, not an answer. It does not name the near-duplicate siblings (hiring_dashboard_link, hr_dashboard_link, analytics_view_link, view_link), which keeps it from 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?

Explicit when-to-use ('when the person you work for asks to see it themselves'), explicit when-not ('Do the work and answer with the area's own tools first; a link never replaces that'), and a concrete trigger ('when an answer would be a long list they would rather look through, offer a link and make it once they say yes'). Nothing 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, idempotentHint and a closed-world scope, so safety is covered. The description adds value beyond that by disclosing the shape of the content (company, country/region, contents), the baseline that all areas use Conecto's database and servers with some using an additional named service, and that the call is free. It stops short of describing pagination or exact return structure.

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

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

Two sentences plus a short purpose tag and cost note; the content-of-return sentence is front-loaded and no sentence is filler. The 'Free.' fragment is terse but 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?

With one optional parameter, no output schema and full annotation coverage, the description supplies what the agent otherwise lacks: what the returned rows contain and the GDPR-driven reason to call it. Only the exact return shape/pagination is left unspecified, which is minor for a simple read.

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 optional 'areas' parameter is documented with an example and a default of 'all'. The description only implicitly references areas ('each area's data'), adding no syntax or filtering 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?

The description names the concrete resource: per-area data storage/processing locations, including the operating company, the country or region, and what is held. That is specific enough to distinguish it from every account_* and books_* sibling, none of which cover data residency, though the verb is implied rather than stated.

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

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

It gives a clear use context — the business's records of processing and transfer assessments under GDPR Art. 30 and 44 — which tells the agent when this tool is the right call. It does not name an alternative or any explicit exclusion, 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?

Goes well beyond the annotations by disclosing per-channel cost ($0.005, free with no subscribers), a 10 KB data limit, and that sent_by is auto-appended with bot and team. Does not mention that repeats are non-idempotent (duplicate events) or what happens on an unmatched kind, which the annotations leave to inference.

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?

Cost is stated twice in near-identical sentences, which wastes space in an otherwise dense paragraph. The delivery model is front-loaded well, but the long parenthetical from the first sentence to the last hurts readability.

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

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

For a mutation tool with no output schema, it covers destinations, payload limits, auto-injected metadata, and pricing—the things an agent needs before calling. Remaining gaps are the semantics of title/text/link and the non-idempotent behavior implied by annotations.

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

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

Schema coverage is only 20%, so the description must compensate; it does for kind (pattern restated with examples), data (any JSON, 10 KB cap) and sent_by (injected, not an input). It says nothing about title, text, or link, leaving three of five params explained only by bare schema types.

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 (send/emit) and resource (event), pins the naming scheme to custom.<name> with two concrete examples, and names where the event lands (subscribed channels plus account_events). This clearly separates it from the read-only sibling account_events.

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

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

Explains the routing model (notify_subscribe with 'custom.*' or exact name) and the downstream alternative of another team's bot picking the event up from account_events. Lacks an explicit 'do not use when…' exclusion, but the context is concrete enough to choose correctly.

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 destructive/idempotent/not-readOnly. The description goes far beyond them: what is anonymised vs deleted vs retained (with reasons surfaced in the result), that the suppression lists block future outreach, that the action is irreversible, and that the owner is emailed. This is genuinely decision-relevant context an agent cannot get 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?

Front-loaded with the action and the precondition, which is good, but the body is a single run-on sentence enumerating dozens of data areas, and 'Free. Free.' is duplicated — an obvious editing artifact. Density is justified by the tool's complexity, but the delivery costs readability.

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

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

For a highly destructive multi-system erasure with no output schema, the description covers irreversibility, the anonymise/delete/retain split, the error path, side effects on outreach, and that the return value carries per-item retention reasons. An agent has enough to call it correctly and to warn the user.

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 real meaning: it explains that 'correspondence' governs whether emails and tickets are deleted or retained for legal reasons, and that email/phone are the identity anchors used for matching and suppression. Only the phone parameter's role is left implicit.

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 ('Erases one person across every area') plus the legal trigger (GDPR Art. 17). An agent can immediately distinguish this from account_export_person or account_find_person, which operate on the same person without destroying data.

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 for invocation ('once you know it is them — they wrote from that address, or confirmed it') and a routing rule for the owner_required case. It never names a sibling alternative, so it stops short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint/idempotentHint/no-destructive, so safety is covered; the description adds genuinely new facts: 30-day retention window, oldest-first ordering, and that calls are free. It omits any mention of rate limits or event object shape, but the added context is substantial.

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 statement and ordering are front-loaded, then the event-family list, then operational notes (retention, polling, cost). Dense and mostly waste-free, though the long semicolon-chained event list is heavier than a shorter enumeration would be.

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 does the heavy lifting by naming what kinds of events appear and how to page through them; an agent could use it correctly without further context. It does not describe the shape of a returned event record, which is the remaining gap for a read tool of this kind.

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

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

Schema covers 67% of parameters ('after' and 'kinds' documented, 'limit' not). The description adds meaning beyond the schema by explaining the polling idiom for 'after' (last event_id you saw) and clarifying the wildcard area syntax indirectly via the 'hiring.*' framing in the schema. Minor gap on limit and default behavior.

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 — reading recent account events caused by actors outside the bot — and enumerates the event families (applications, bookings, form responses, signatures, emails, goals) plus custom events from account_emit_event. This makes it easy to distinguish from account_audit_log and from the write-side sibling account_emit_event.

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

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

Gives an explicit consumption pattern — 'Poll with after = the last event_id you saw' — and implicitly delineates scope as external-actor activity versus bot-emitted custom events. It does not explicitly say when to prefer it over account_audit_log, so it stops short of 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?

Goes well beyond the annotations: discloses that the job is asynchronous with a call_id and download link per part, that credentials are excluded, that parts are decryptable only by this key and by owner/admin keys with sufficient permissions, and that a non-company team key gets owner_required. It also warns that the owner is emailed and that free-tier quotas apply, so the agent knows the side effects of a non-readOnly, non-idempotent 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?

The core content is front-loaded and useful, but there is real duplication: 'Free' is stated twice and the background/polling instruction is given twice with different wording ('poll the call with account_get_call; the result has a download link for each part' vs 'the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>'). The garbled sentence about which keys can open the parts also costs clarity.

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

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

For a zero-parameter, no-output-schema job tool, the description carries the burden well: it explains what is produced, how to retrieve it, and what access and quota rules apply. It omits retention/expiry of the download links and leaves the key-permission rule phrased ambiguously, which is the only gap.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly offers no parameter discussion.

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 with precise scope: everything the account holds, as JSON Lines per area plus stored files, in ZIPs up to 24 MB written to the file store. That scope distinguishes it from the narrower account_export_person and books_export siblings without needing to name 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?

Gives clear operating context: it is an asynchronous job, you must poll with account_get_call, and it is rate limited to one at a time and three per day. It never explicitly routes the agent to account_export_person or books_export for narrower exports, so the alternative-selection guidance is implied only by scope.

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?

Placeholder

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?

Placeholder

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?

Placeholder

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?

Placeholder

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 and resource ('everything account_find_person finds about one person in one ZIP') and enumerates the contents (JSON Lines records minus credentials, plus referenced files like a CV). An agent can distinguish it from account_export_all and account_find_person 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 a clear 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?

Annotations already cover read-only, idempotent and non-destructive, so the bar is lower; the description still adds real value by disclosing the return shape ('each kind with its count and ids') and that the call is free. It stops short of stating match strictness (exact vs. partial), result caps, or what happens with zero hits, which for a read with no output schema would be useful.

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 verb and scope, and each sentence carries distinct information (purpose, GDPR use case, return shape, alternatives, cost). The long enumeration of areas is partly redundant with 'across every area' and 'with their chats and CRM history', which is the only wasted space.

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-param lookup with annotations covering the safety profile and no output schema, the description covers purpose, trigger, return contents, cost and sibling routing. Nothing an agent needs in order to choose and call this 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% and both properties already document their formats, so baseline is 3. The description adds one meaningful nuance the schema does not — that either an email or a phone can identify the person — but does not say whether both may be supplied together or how they are combined.

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 ('Every record this account holds about one person') with an explicit scope ('across every area') and an explicit matching key (email or phone). It also names the two closest siblings, account_export_person and account_erase_person, so an agent can differentiate 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 a concrete triggering scenario ('For a person who asks what the business keeps about them (GDPR Art. 15)') and routes the adjacent intents away: export for a copy, erase for deletion. When-to-use and the alternatives are both spelled out, not 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description's only behavioral contribution beyond that is the cryptic 'Free', which reads as a stray fragment rather than a disclosed trait (no-cost read? free tier?) and is not explained.

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 is appropriately sized, but it is a verbless noun phrase followed by a dangling 'Free.' fragment, so it is not front-loaded with an action the agent can act on. The trailing 'Free' does not earn its place without 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 no-param, read-only tool with full annotation coverage and no output schema, the description is close to sufficient but omits what actually comes back (e.g. a URL vs. raw values) and never states the read action. It is adequate rather than complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The enumeration of brand fields is a small bonus that hints at the returned content.

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 enumerates what the brand consists of (name, logo, colour, footer line) and where it appears (emails and published pages), which is genuinely informative about the resource. But it never states the action – that these values are returned/read – so the verb is only inferable from the tool name. The sibling account_set_brand is not mentioned, so nothing distinguishes get from set.

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

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

There is no statement of when to call this versus account_set_brand, or any prerequisite such as authentication or account scope. The single word 'Free' gestures at a cost condition but is not framed as guidance. The agent must infer usage entirely from the name.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive), and the description adds useful behavioral context: the call status values, returned cost/result, and polling usage. It does not describe auth or rate limits, but adds meaningful detail beyond 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 short sentences, front-loaded with the core action and return fields, followed by usage guidance and a useful cost note. 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 read tool with annotations and no output schema, the description covers the key return values and polling use case well. Minor gaps around missing/invalid call IDs or exact response shape remain, but the essential context is present.

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

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

Schema description coverage is 0%, so the description must compensate for the single call_id parameter. It only says the lookup is 'by id' and does not explain where the ID comes from or its expected format, leaving the schema to carry nearly all parameter meaning.

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

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

The description gives a specific verb and resource ('One call by id') and names the returned fields (status, cost, result). It clearly distinguishes a single-call fetch from the sibling list operation.

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

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

It explicitly states the primary use case: polling a background call until it finishes. It does not mention when not to use it or point to account_list_calls for discovering call IDs, but the intended context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two real signals beyond that: the returned fields (standard, current, maximum, plus past requests and answers) and that the call is free of charge. It says nothing about auth requirements or pagination of the requests list.

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 dense sentence with no filler; the parenthetical examples of limit kinds are the one mildly expendable element. The payload (what is returned) 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?

There is no output schema, so the description must describe the response, and it does: per-limit standard value, current value, maximum askable value, plus the business's requests and their answers. For a zero-parameter read tool with full annotation coverage, nothing an agent needs 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 no-parameter tool 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 read of a specific resource: the account's limits, their standard/current/max values, and the business's limit requests with answers. It is clearly distinguishable from the sibling account_request_limit by describing only retrieval. However, it never names that sibling to make the read-vs-request split explicit.

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

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

Usage is only implied: an agent infers it should call this to inspect limits before calling account_request_limit. There is no explicit 'use when' or 'do not use when' statement, and no prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description does add value beyond them by disclosing a cost trait ('Free', presumably no quota/credits consumed) and by indicating the payload includes thresholds and approvers. It omits ordering, pagination, and whether inactive rules are included.

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

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

Two short sentences with no filler, and the substantive content leads. The telegraphic 'Free.' at the end is efficient but under-explained, and the opening phrasing reads awkwardly.

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 no-parameter read with full annotation coverage and no output schema, the description covers the essentials: what the records are and roughly what fields come back. It still leaves open whether all rules or only active ones are returned, and what 'Free' actually constrains.

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; baseline 4 applies. The mention of thresholds and approvers usefully previews what the result records contain.

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 gestures at approval rules ('the tools that wait for a person's approval, with their thresholds and approvers'), but calling them 'tools' rather than 'rules' muddies the subject, and it never states plainly that this returns the account's configured approval rules. An agent can roughly infer the resource, but the verb and the object are not clean.

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

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

There is no when-to-use guidance and no mention of the obvious alternative, account_add_approval_rule, which creates the very objects this lists. 'Free' hints at cost but says nothing about selection criteria 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral facts: results are sorted newest first, scoped to this account, and "Free" (no billing/quota cost). It does not mention pagination or windowing beyond "recent".

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?

Roughly twenty words, front-loaded with the resource and ordering, and every clause carries a filter or a behavioral fact. The telegraphic phrasing ("or one area's") is slightly clipped but not wasteful.

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

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

With no output schema, the description should tell the agent what a returned call record looks like, and it does not. Combined with an unstated limit parameter and an undefined notion of "call", an agent cannot reliably predict the response shape before invoking.

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

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

Schema description coverage is 0%, so the description must carry the parameters and it only half does. It explains status as failed/succeeded but omits the reserved and running enum values, gestures at area ("one area's") without explaining its 52-value enum, and never mentions limit, its default of 20, or the 100 ceiling.

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 and its scope ("Recent calls on this account") and states an ordering, so the basic operation is inferable. But it never says what a "call" is here – the sibling list contains phone_list_calls/phone_get_call, so an agent cannot tell whether this is phone call history or logged API/tool invocations. The verb is also only implied by the title.

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 names optional filters (failed/succeeded, one area) but gives no when-to-use guidance and no alternative. Nothing tells the agent to prefer account_get_call for a single record or phone_list_calls for telephony, both of which are adjacent siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that content is returned 'as they are now' (live, not cached) and that calls are free, but says nothing about volume, ordering, or pagination for what is implicitly a full enumeration.

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 dense sentence front-loads the resource and its scope, then the returned fields, with the parenthetical category list doing real work in telling the agent what is covered. The trailing 'Free.' is terse but earns its place as a cost signal.

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 and no parameters, the description carries the return-value burden and does so by naming the concrete fields (timing, subject, headline, opening words, variables). Only ordering/volume expectations are missing, which is minor for a small per-account listing.

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; there is nothing for the description to disambiguate and no risk of a caller guessing at argument 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 enumerates exactly what the tool returns: every customer-facing email type (bookings, invoices, newsletter sign-ups, etc.) plus send timing, subject, headline, opening words and available {variables}. That is a specific resource picture, but the verb 'list/retrieve' is only implied and the sibling account_set_email_template (the write counterpart) is never referenced to sharpen 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives even though account_set_email_template sits adjacent in the sibling list as the editing counterpart. The 'Free.' tag signals cost of calling but not the selection context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: deterministic ordering (company-wide team first), the fact that paused teams and keys are included, and that the call is 'Free' (no billing impact). It does not address pagination or completeness of the result set.

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

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

The core content is front-loaded, but it is delivered as one very long run-on sentence enumerating roughly seven aspects of each team. The trailing sentence 'A person's own assistant works within their teams' is unclear and does not obviously help an agent decide or invoke; the field list would be far easier to parse as a structured enumeration.

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 burden of describing return values, and it does so thoroughly: areas, read-only flag, budget type/period/alert line, period spend, ERP code, paused state, keys, and members with manager. What's missing is ordering of the non-company teams and whether the result is paginated or truncated.

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. Nothing in the description contradicts or needs to explain a request shape.

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 it returns the account's teams with the company-wide one first, and enumerates what each team record contains. It's clear this is a read of team configuration, though the verb 'list' comes from the title rather than the description. No sibling also lists teams, so no sibling-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?

There is no explicit when-to-use or when-not guidance, and no alternative tool is named. The phrase 'A person's own assistant works within their teams' gestures at context but doesn't tell an agent when to call this versus siblings like account_find_person or account_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?

Adds genuinely non-obvious traits the annotations don't carry: single use, 30-minute validity, passwordless, and no cost. That is exactly the operational detail an agent needs before handing a credential out. Minor tension: a credential-minting, single-use artifact sits oddly beside readOnlyHint/idempotentHint=true, though nothing persistent is mutated.

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 front-loaded 'a link that signs the owner in with no password' is strong, but the middle becomes a disorganized run-on ('the balance, adding credit, auto-reload, limits, what the bots did, people, rentals and keys') that reads as a page inventory rather than wording tuned to page selection. The trailing 'Free.' is a fragment that would be better merged.

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 does the necessary work: it says the return is a link, that it expires in 30 minutes, that it is single use, and what the recipient does with it. It stops short of stating the return type/format explicitly or the consequence of requesting a second link.

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

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

Schema coverage is 0% and the single 'page' parameter has nine enum values, but the description only names two of them ('people' for role assignment, 'settings' for email-domain joins) and never addresses the 'home' default. It conveys that the page decides where the owner lands, which is real added meaning, but leaves most of the enum unmapped.

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?

Identifies a specific resource (a passwordless sign-in link for the business owner) and its effect (signs the owner into their Conecto page). It never uses an action verb like 'generate' and never distinguishes itself from the sibling account_dashboard_link, which is the nearest ambiguity an agent will face.

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?

'Hand it to the owner' gives the downstream action, and the middle sentence hints at when to target a specific page (people, settings for domain join). But there is no explicit when-not guidance, no mention of account_dashboard_link or account_set_owner_email as alternatives, and no stated prerequisites (does the owner need to exist / have an email?).

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 the generic flags; the description adds the substantive behavior: all keys stop, calls are refused, and the state persists until the owner resumes on their account page. It also discloses that the call is free. It omits who is permitted to invoke it and whether an already-paused team errors out (relevant given idempotentHint=false).

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 and short, but the duplicated "Free. Free." is dead weight and the clause "this one too if it is the team's" is ambiguous enough to cost the reader a re-read. Trimming those two would make this a tight two-sentence definition.

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

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

For a mutating one-param tool with annotations and no output schema, the effect and recovery path are covered, but the missing identifier format and the missing permission/precondition info leave an agent without what it needs to call this confidently.

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

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

Schema description coverage is 0% for the single required "team" parameter, so the description must compensate and does not: nothing says whether "team" is an ID, a slug, or a display name. The phrase "this one too if it is the team's" is confusing and does not clarify the 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?

"Stops every key of a team at once" states a specific verb (stops) and resource (team keys) and clarifies the blast radius is all keys, not one. It is clearly distinguishable from account_save_team or account_assign_team, though it never names a sibling to differentiate against.

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?

"For a bot that misbehaves or a team that spends too fast" gives concrete trigger scenarios, and "until the owner starts the team again" implies reversibility. But there is no explicit when-not guidance (e.g. pausing a single key vs. the whole team) and no alternative tool named.

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

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

Beyond the destructiveHint annotation, the description explains the financial effects: credit and first top-up bonus leave the balance, the card is credited back with tax, and the service fee is kept. This is exactly the kind of consequence detail an agent needs before invoking a destructive refund 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?

The description is front-loaded with the refund action and key constraints, but it is awkwardly phrased and contains a duplicated trailing sentence: 'Free. Free.' That redundancy and the run-on eligibility sentence reduce polish.

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 destructive tool with no output schema, the description covers eligibility, default behavior, financial effects, and fee treatment. An agent has enough information to decide whether and how to call it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so by explaining that topup_id is optional and that omitting it refunds the newest top-up, with GET /v1/topups as the way to list ids.

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

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

The description states a specific verb and resource: refund a top-up. It also specifies the core eligibility condition (paid in the last 24 hours and unused), so the agent can distinguish this from unrelated account and books 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 clearly states when the tool applies: a top-up paid in the last 24 hours that has not been used. It also explains the default behavior when topup_id is omitted, though it does not name a sibling alternative or explicitly describe when not to use it.

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

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

Goes well beyond the annotations by disclosing that the outcome is asynchronous (account.limit_request_answered event plus email to the owner), that approval may be partial ('maybe with less'), and that the owner is notified immediately as a side effect. That is exactly the mutation-and-notification context the readOnlyHint=false / destructiveHint=false pair does 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?

Front-loaded with the core action and dense with useful facts in two sentences, but it ends with a duplicated 'Free. Free.' and packs the eligibility, throttling and async-answer mechanics into one overloaded clause.

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 correctly explains how the answer arrives (event plus owner email) rather than what is returned. It stops short of saying whether a request identifier is returned or how to check a pending request, which an agent handling a follow-up would want.

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 all four parameters are already documented, including the enum list, the 40–2000 character reason bounds and the `other` fallback. The description restates those facts ('which one (or other, saying which)', 'the number it needs', '40 to 2,000 characters') without adding format or unit guidance the schema lacks, 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?

Names a specific verb and resource: asking Conecto to raise one of the business's limits, with the inputs spelled out. The read/write split against account_get_limits is obvious from the phrasing, but the description never names that sibling, so the differentiation is inferred rather than stated.

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

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

Gives concrete eligibility and throttling conditions: only for an account that has topped up, one request per limit at a time, five in 30 days, and free. It lacks an explicit alternative or exclusion (e.g. 'to see current limits use account_get_limits', 'do not use for billing/top-up issues, use account_refund_topup'), which keeps it below 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?

Beyond the annotations, it discloses the hard-vs-soft budget enforcement outcome ("a hard budget refuses the call that would pass it, a soft one only warns"), the alert event and email emitted at alert_percent, key-scoping effects of read_only/drafts_only/mailboxes, the special company-wide team behavior, and the cost model including no charge on failure. None of this is inferable from readOnlyHint/idempotentHint alone.

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

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

It is a single dense paragraph in which the most important fact (this tool creates or changes a team) appears only after a long definitional preamble, making it hard to scan. The cost is stated twice ("$0.001." and "Costs $0.001 per call; nothing if it fails."), which is wasted space in an otherwise information-dense description.

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 13-parameter upsert with no output schema, the description covers permissions, budget enforcement, alerting, drafting/mailbox scoping, the company-wide special case, and billing behavior. The only gap is the return value, which is not critical for calling the tool correctly.

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

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

Schema coverage is 77%, so the baseline is around 3, but the description adds real meaning: budget_period is tied to monthly_budget_usd, budget hard/soft behavior is spelled out, erp_code is contextualized as a cost center for statements, and drafts_only is explained as writes waiting for a manager or owner. Some parameters (name, new_name, alert_percent range) get no narrative help beyond the schema, keeping it out of 5 territory.

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 defines the resource precisely ("A department, location or project group of the account...") and later states the operations it performs ("You may make a team and narrow one"), so an agent can identify it as the create/update tool for teams. However, the actual verb+action is buried mid-paragraph rather than front-loaded, and the distinction from siblings like account_list_teams or account_pause_team is only implicit.

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

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

It draws an explicit boundary of what this tool can do (create a team, narrow its areas) versus what only the owner can do on the account page (widening areas, enabling writes, ending drafts-only, soft-to-hard budget switching, raising/removing budgets), including the precondition "when the account has an owner email." That is a clear when/when-not with a named alternative path.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add operational context, which it does: conjunctive case-insensitive matching, ranking (titles first, then newest), and the fact that each result names the tool that opens it. Pagination and result-count behavior remain unspecified.

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 purpose, then matching rules, ranking, and result format in tight sentences. The long enumeration of content types is informative but stretches the first sentence; nothing else 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?

Covers purpose, matching semantics, ranking, result shape, narrowing, and cost, which is enough to call it correctly even without an output schema. The only real gap is how many results come back by default and how limit interacts with the 50 maximum.

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

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

Schema description coverage is 0%, so the description must carry the load; it defines query semantics ('Every word must appear (any case)') and the purpose of areas ('Narrow it with areas'), which the enum alone would not explain. The limit parameter, including its default and 50 cap, is left entirely to 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 ('One search over what this account holds') and enumerates exactly what is searched, from files to CRM records to book entries. An agent can distinguish this cross-domain search from the many single-domain 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?

'Narrow it with areas' gives clear narrowing guidance, and 'Free' signals there is no cost barrier to calling it broadly. However, no alternative is named and no when-not-to-use case is given, despite siblings like account_find_person or account_list_calls that overlap with the CRM and email scopes.

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

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

It provides highly valuable behavioral constraints beyond annotations, such as listing every specific location of brand usage (e.g., 'forms, status, views'), specifying file formats for the logo (PNG, JPEG, etc.), and critically, stating 'Only what you pass changes; an empty string clears 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?

The description is dense and long, which reduces conciseness. However, this length is necessary to cover the vast scope of affected systems and behavioral rules, making the verbosity justified.

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 description is exceptionally complete, detailing not only the parameters but also the cost of the operation and the exact scope of its influence across the application, addressing potential agent questions about side effects.

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?

Given the very low schema coverage (20%), the description is essential. It explains the functional purpose of each parameter (e.g., 'Hex, like #1a73e8' for color) and defines critical operational semantics like using an empty string to clear a setting.

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 explicitly states the goal: setting the business's brand (name, logo, color, and footer). This is immediately clear and distinguishes it from potential retrieval tools like `account_get_brand`.

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 tool clearly defines its comprehensive scope—branding applies to all customer emails and published web pages. It doesn't compare it to other setters, but its detailed list of effects defines its operational niche well.

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?

Goes well beyond the annotations by disclosing cost ($0.001 per call, free on failure), the reversibility contract (empty string restores the original), the blast radius (facts, links and buttons are untouched), and the text format rules (plain text, blank line = new paragraph). These are all consistent with destructiveHint=false and idempotentHint=true.

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 tight sentences, front-loaded with the verb and scope, then the dependency, the reversibility rule, the formatting rule and the cost. No filler, and each sentence carries a fact an agent needs to call it correctly.

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

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

For a 4-parameter mutation with no output schema, the description covers scope, cost, failure behavior, variable sourcing and formatting. It does not say what the response contains or whether the change is immediately live, but with no output schema that gap is minor.

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

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

Schema coverage is only 25%, so the description carries real weight: it explains the empty-string reset semantics, the {variable} placeholders permitted in values, and the plain-text/blank-line formatting for the text fields. It leaves the mapping of individual parameters (e.g. which field the 200 vs 4000 character limits apply to) to the schema, which is acceptable.

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

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

States a specific verb and resource ('Change an email's subject, headline or opening words') and bounds the scope explicitly: the underlying facts, links and buttons stay fixed. It also names the sibling read tool it depends on (account_list_email_templates), so an agent can distinguish it from listing or brand 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 clear operative context: variables must come from account_list_email_templates ({name}, {when}), and passing an empty string reverts to the original wording. It stops short of explicit when-not-to-use guidance (e.g. that this cannot change times, places or amounts, only the wording), so it lands at clear-context-but-no-exclusions.

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

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

Beyond the annotations, the description discloses meaningful behavior: the effect is deferred ("Nothing changes until they open the link") and the consequences of confirmation (owner receives warnings and approval requests, only the owner raises limits). It also signals the call is free. It omits what happens on repeat invocation, which matters given idempotentHint=false, and the duplicated "Free. Free." suggests a drafting error.

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

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

The text is short and the precondition is front-loaded, but the trailing "Free. Free." is a literal duplication that wastes space and looks like a copy error. The sentences otherwise earn their place by explaining the confirmation flow.

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

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

For a single-parameter mutation with no output schema, the description covers the effect and the deferred activation, which is the essential mental model. It is still missing re-invocation semantics and the overwrite/conflict case for an account that already has an owner, gaps that matter for a non-idempotent write.

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

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

Schema coverage is 0%, so the single parameter carries no structured documentation. The description implicitly identifies it as the owner's email address ("send that person a link"), which is useful, but it says nothing about format, validation, or what happens if the address is wrong or already in use.

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 concrete action: sending a confirmation link to the owner's email so they can claim ownership of the account. It is clear what the call accomplishes, but it does not distinguish itself from the sibling account_owner_link, which an agent could easily confuse with this tool.

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

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

"When the account was made without the owner's email" gives an implied precondition for use, which is more than most tools offer. However, there is no guidance on when NOT to use it (e.g., when an owner already exists) and no mention of the account_owner_link or account_assign_team alternatives.

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?

Goes well beyond the annotations: discloses the confirmation email and calendar invite side effects, that only the attendee (when an email is supplied) gets a reschedule/cancel link while guests do not, that round-robin picks the host by rules unless one is named, and the per-call cost and failure pricing. That is exactly the kind of side-effect and cost context annotations cannot carry.

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

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

Front-loads the core action in the first clause and packs cost, side effects and the round-robin rule into four tight sentences. The middle sentence about who receives links is dense and takes a second read, but 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?

For a 12-parameter mutation tool with nested answers and no output schema, the description covers pricing, side effects, notifications and host routing well. The notable gap is the return value — nothing says whether the call yields a booking identifier that calendar_cancel or calendar_move would need, which the missing output schema would otherwise have to supply.

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 only 58% schema description coverage, the description usefully explains several undocumented parameters: email gates the self-service reschedule/cancel link, guests are invited by email without that link, host overrides round-robin rules, and confirmation_call_agreed is a consent flag rather than a scheduling option. It still says nothing about timezone, answers, phone, notify or person, so the compensation is partial.

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 ('Book a free time ... for someone') and immediately ties it to the sibling that produces the input ('from calendar_find_times'). An agent can tell this apart from calendar_find_times, calendar_move and calendar_cancel 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 names the prerequisite source of the slot (calendar_find_times) and gives a conditional rule for confirmation_call_agreed ('only if the person agreed to a call before the meeting'). It does not say when to prefer this over the Google/M365 calendar_create siblings or over calendar_move for changing an existing booking, 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?

The annotations already declare the tool as destructive, non-read-only and idempotent. The description adds meaningful context beyond that: notification emails to attendee, guests and hosts, the notify=false opt-out, and per-call cost including failure pricing. It does not say whether cancellation is reversible or what authorization is needed, so it stops short of a 5.

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

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

Three short sentences, front-loaded with the action, then side effects, then billing. Every sentence adds useful information without repetition or 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 destructive, idempotent mutation tool with annotations and no output schema, the description covers the key side effects and cost model. It is still incomplete for invocation because the booking identifier's source/format and the purpose of reason are not explained.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It clarifies notify semantics only, and leaves the required booking parameter and the reason parameter undocumented in both schema and description.

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

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

The description states a specific verb and resource: 'Cancel a booking.' This is clear enough to distinguish it from calendar_book or calendar_move. However, it does not name sibling cancellation tools such as google_calendar_cancel or m365_calendar_cancel, so the agent must infer the routing from the tool namespace.

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 guidance is provided, such as pointing to calendar_list_bookings to find a booking ID before cancelling. Alternatives and prerequisites are left entirely implicit.

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

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

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, but the description adds genuinely new behavioral context: the link is single-use with a one-hour expiry, Google emails the attendee an invitation, and read/draft-only API keys receive "[redacted]" instead of a usable link. The only gap is the mild tension between idempotentHint=true and a link that works exactly once, which is left unexplained.

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 core behavior — what the link is, who it targets, that it is single-use for an hour — is front-loaded in the first sentences. The remaining sentences about Outlook, redaction, and pricing are dense but each adds actionable information, though the overall flow reads as run-on prose rather than clearly separated concerns.

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

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

With no output schema, the description still tells the agent what comes back (a link, or "[redacted]"), how long it lives, what happens downstream (busy-time avoidance, calendar entries, attendee invitations), and what to do next. Only the permission model's exact boundaries and the idempotency question are left fuzzy.

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

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

Schema coverage is only 50%, so the description has to carry weight — and it does: it explains that `person` (email) switches the target from the business calendar to that individual's own. The undescribed `provider` enum is implicitly constrained to Google by the surrounding text, which notes Outlook goes through microsoft365 instead.

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 — it produces a one-time link that connects a Google calendar — and clarifies that the link targets either the business's calendar or, with `person`, that person's own. It distinguishes itself from the Outlook path by pointing at the microsoft365 tools, though it never mentions the nearby `google_connect` sibling, leaving some ambiguity about which one actually performs the connection.

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 names the alternative for Outlook calendars (the microsoft365 tools) and states the follow-up step: after connecting, select the calendar via `calendar_setup connected_calendar_id`. What is missing is an explicit when-not-to-use note relative to `google_connect`, which sits right next to it in the tool list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: a hard 62-day range cap, timezone-of-choice output, and per-host filtering for round-robin types. It doesn't describe the shape of returned slots (e.g., count/density), so not a 5.

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

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

Three short sentences, front-loaded with the core capability, then the round-robin caveat, then the next-step pointer. 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 read-only finder with no output schema, the definition covers inputs, limits, and timezone behavior well. It leaves the returned slot format implicit, a minor gap against the complexity of the 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?

Schema coverage is 67%, and the description adds the 62-day from/to constraint that the schema does not encode, plus clarifies why host matters (round-robin only that host's times). It doesn't elaborate on the person/meeting_type slug composition beyond what the schema 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+resource (free start times for a meeting type) plus the date scope and timezone behavior. The round-robin host clause and the 'Book one with calendar_book' pointer clearly distinguish it from calendar_book and calendar_list_meeting_types.

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 follow-up action to calendar_book and clarifies the round-robin case. It doesn't state when not to use it or point to calendar_list_meeting_types as the way to obtain a meeting_type slug, so usage is clear but not fully closed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description still adds value beyond that by disclosing what the response contains and that the call is 'Free' (no cost/billing), a behavioral trait not present in the annotations. It stops short of saying how missing or invalid configuration is handled.

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 resource and its contents are front-loaded in a single dense sentence, followed by a short parameter note and 'Free.' Almost every clause earns its place, though the trailing fragments read telegraphically and 'Free' is ambiguous without context.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so by enumerating the exact sections returned and how they differ for the business vs. personal calendar. For a one-parameter read tool with annotations covering safety, this is complete enough to call correctly.

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

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

Schema coverage is 100% and the schema documents the single 'person' parameter, so the baseline would be 3. The description adds real semantics on top: it clarifies that omitting 'person' yields the business calendar and that the parameter scopes to an individual's own calendar, which is the default-vs-override behavior the agent needs.

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

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

Specific verb ('Get') plus a detailed enumeration of the resource: settings, booking page, iCal subscribe link, connected Google calendar, confirmation calls, and — for the business calendar — meeting types and people's calendars. It's far more than a restatement of the name. It does not, however, distinguish itself from siblings such as calendar_setup or calendar_list_meeting_types, leaving the agent to infer which one to call.

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?

'person reads someone's own calendar' implies the default is the business calendar and that the parameter switches scope, which is useful usage context. But there is no explicit when-to-use/when-not guidance and no pointer to the alternative tools (calendar_setup for changes, calendar_list_meeting_types). Usage is implied 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 cover the read-only/idempotent safety profile, so the description's added value is the default window ('from now on'), the sort order ('soonest first'), and the payload contents (hosts, guests, confirmation call). One weakness: the trailing 'Free' is unexplained and the default exclusion of cancelled bookings is never 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?

Three compact, front-loaded sentences with no filler; the core scope appears in the first clause. The single trailing word 'Free' is ambiguous and earns little.

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 does well to name the returned fields, but a six-parameter list tool with a status enum and a limit cap should disclose the default status and pagination limit. Missing that, the definition is adequate but has clear gaps.

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

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

Schema description coverage is only 17%, so the description must carry parameter meaning and it largely does not. It explains `from`/`to` defaults and `person`, but leaves `limit`, `meeting_type`, and critically `status` (default 'scheduled', so cancelled bookings are silently hidden) undocumented.

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

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

States a specific verb and resource ('bookings between two times') and even describes what each returned booking contains (hosts, guests, confirmation call). It does not explicitly contrast with calendar_find_times or google_calendar_events, so sibling differentiation is only implicit.

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

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

Usage is implied by the date-range framing and by the one routing hint ('person lists the meetings that person has'), but there is no explicit statement of when to prefer this over calendar_find_times or the google/m365 calendar tools. The agent must infer the choice.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds useful context beyond that: the return shape (meeting types with booking pages), the ordering, the shared 'meeting_type' naming convention, and that it is 'Free'.

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 dense but efficient and front-loads what is returned. The trailing 'Free' is terse but informative; nothing is wasted, though the phrasing is slightly informal.

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 naming what is returned and the ordering. Annotations cover the safety profile, and the single parameter is well documented, leaving no critical gap.

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

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

Schema coverage is 100%, so the schema already documents the optional 'person' parameter. The description adds the nuance that passing person returns 'only theirs', clarifying the filtering behavior beyond the schema's 'their own calendar instead of the business's'.

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

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

The description clearly states it lists meeting types with their booking pages, including the business's and each person's own, and clarifies that 'meeting_type' is the term other tools use. It distinguishes the content from calendar_list_bookings and calendar_list_routing_forms implicitly, though it does not name a sibling directly.

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

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

Usage is implied through 'person lists only theirs' and the ordering (business's, then each person's own), but there is no explicit when-to-use statement or comparison against alternatives like calendar_get_setup or calendar_save_meeting_type. The agent must infer the context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description contributes the return-shape detail and the odd trailing word 'Free', which hints at cost/quota but is never explained. No mention of ordering, pagination, or volume limits for a list endpoint.

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 that leads with the resource and its fields. The trailing fragment 'Free.' is ambiguous and arguably does not earn its place without elaboration.

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 input parameters and no output schema, the description usefully enumerates the returned fields, which is the main thing an agent needs. Remaining gaps (pagination, ordering, empty-state behavior) are minor for a zero-arg read.

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; baseline 4 applies. Nothing in the text misleadingly implies filtering options that do not exist.

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 (routing forms) and enumerates the payload it carries: addresses, questions, routes, and per-form answer counts. That is clearly a read/list operation, and the 'how many people answered each' clause separates it from the sibling calendar_list_routing_responses at a conceptual level, though the 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?

No statement of when to call this versus calendar_list_routing_responses (raw responses) or calendar_save_routing_form (mutate). The agent must infer the routing from the tool name alone, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: sort order (newest first), the payload contents, and the fact that calls are free. It says nothing about pagination behavior or how many records come back.

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 that defines the resource first and enumerates the return contents. Efficient with no filler; the trailing 'Free' is slightly abrupt but carries real information.

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

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

For a read-only list tool with no output schema, the description covers what is returned, ordering, and cost, which is a reasonable baseline. However, with 3 filter parameters and only partial schema documentation, the agent lacks enough to know how 'form' scoping or 'person' affects results, or how to page through data.

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 description never mentions any of the three parameters. Schema coverage is 67%: 'form' and 'person' are documented in the schema, but 'limit' has no description beyond default/min/max bounds. With coverage below 80%, the description was expected to compensate for the undocumented limit semantics and did not.

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 pair (listing routing-form answers) and adds scope detail: answers, their destination, and the resulting booking, ordered newest first. It does not explicitly distinguish itself from siblings like calendar_list_routing_forms (the forms themselves) or forms_list_responses (non-routing form answers), so the 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?

There is no when-to-use guidance and no named alternative. 'Free' hints that this costs no credits, but nothing tells the agent when to pick this over calendar_list_routing_forms or forms_list_responses, nor any prerequisites for reading answers.

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?

Goes well beyond annotations by disclosing that attendees and guests receive updated email invites, how round-robin host selection behaves, and the $0.01 per-call cost with no charge on failure. These are important side effects and billing details for a mutation 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?

Front-loads the core action and is generally efficient, with four sentences that each contribute useful information. The round-robin detail is specialized but still relevant to 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?

Covers side effects, cost, and round-robin behavior, but omits how notify=false affects emails and what happens if the requested time is unavailable. For a mutation tool with no output schema and incomplete parameter documentation, this leaves meaningful gaps.

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

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

Schema coverage is only 33%, and the description does not explain the notify parameter or clarify how start interacts with the booking. It adds little parameter meaning beyond the schema, especially for the undocumented notify flag.

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: "Move a booking to another free time." This clearly distinguishes it from sibling creation/cancellation tools like calendar_book and calendar_cancel.

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 context for use is clear—moving an existing booking—but it gives no explicit alternatives such as using calendar_find_times to locate free time or calendar_cancel to cancel instead. Usage is implied rather than guided.

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

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

Goes well beyond the annotations (idempotent, non-destructive) by disclosing partial-update semantics ('Only the fields you pass change'), cost ('$0.001 per call; nothing if it fails'), and rich domain behavior for assignment modes, host scheduling, and location kinds. This is exactly the extra context annotations cannot carry.

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

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

Wait — this is dense but nearly every clause carries distinct domain meaning (hosts, hours, assignment, location). However it is delivered as a single run-on paragraph with convoluted nested parentheticals (the round_robin priority/weight/recency chain), hurting parseability. Downgraded for 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 20-param, nested-object tool with no output schema, it supplies substantial domain context covering the hard concepts. It omits any statement of what the tool returns on success, and several scalar params are undocumented, leaving a modest 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?

With 60% schema coverage and 20 params, the description adds real meaning for the complex ones: round_robin vs collective semantics, priority/weight/fixed interplay, hours overriding, and the location kind enumeration. Some simpler params (buffer_before/after, notice_minutes, title, active) are left to the schema, so it doesn't fully compensate for every gap.

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

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

States a specific verb pair ('Create or change') and resource ('a kind of meeting people can book, like a Cal.com event type') and adds the outcome ('it gets its own booking page'). An agent can clearly distinguish this write/upsert tool from calendar_list_meeting_types or calendar_book.

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 'Create or change' and 'Only the fields you pass change' (an upsert/PATCH hint). It never explicitly states when to reach for this versus calendar_setup, calendar_list_meeting_types, or calendar_book, nor any prerequisites or exclusions.

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

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

Goes well past the annotations (which only say non-readOnly, idempotent, non-destructive) by disclosing the per-call cost ($0.001), that failures are free, that each answer set is persisted, and that a calendar.routed event fires — genuinely useful side-effect information an agent cannot get from structured fields. The partial-update rule ('only the fields you pass change') also reinforces and sharpens the idempotentHint.

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?

Dense and front-loaded: the core action comes first, followed by routing semantics, URL, then cost/side effects. Nearly every sentence carries information, though the single long block is heavy and could be split for faster scanning.

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

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

For an 8-parameter, nested-object mutation with no output schema, the description supplies the conceptual model (questions → routes → fallback), the update semantics, the resulting address, the cost, and the emitted event — everything an agent needs to call it correctly without guessing.

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 63% schema coverage and deeply nested routes/fallback/questions, the description earns its keep by explaining route evaluation ('first route whose conditions all hold wins; everyone else takes the fallback') and the special meaning of name/email question keys pre-filling the booking form. It does not explain the simple fields title, active, person, or description, so it is not fully compensating for the coverage gap.

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

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

Opens with a specific verb+resource ('Create or change a routing form') and then defines the resource concretely — questions, routes, fallback, URL shape — so it is unmistakably distinct from calendar_list_routing_forms, calendar_save_meeting_type, and forms_create. An agent knows exactly what it is saving and where it appears.

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 makes the create-or-update semantics explicit ('Only the fields you pass change') and points to calendar_list_routing_responses for answer sets and the calendar.routed event for downstream consumers, which gives clear situational context. It does not, however, state when to prefer this over building a plain booking flow or an alternative form tool, so it falls short of the explicit when/when-not bar.

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 idempotent/non-destructive, but the description adds material context they don't carry: upsert semantics (first call creates), partial-update semantics (only passed fields change), per-call cost ($0.001, free on failure), downstream reminder cost ($0.002, paid accounts only, no reminder for late bookings), and address reclamation behavior (old address forwards, no other business can take it). That is exactly the kind of side-effect and billing disclosure an agent needs 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?

Every sentence carries load — no filler, and the create/partial-update/cost facts are all actionable. The weakness is structural: the opening sentence is a single sprawling construction with a nested parenthetical definition of "person" and a colon-delimited field list, which costs the reader a re-parse even though the verb and resource do come first.

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 11-parameter tool with nested objects and no output schema, the description covers the entity model (business vs person calendar), the create-vs-update lifecycle, the follow-on tool, prerequisites for connected_calendar_id, and the cost model. The main residual gap — what the call returns — is largely mitigated because the natural upsert pattern and calendar_get_setup reference make the read path discoverable.

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 91%, so the baseline is 3 and the schema does most of the work. The description still contributes meaning the schema doesn't: that no fields are required because the first call creates the calendar, and that omitted fields are left untouched rather than reset. It doesn't add format or interaction detail beyond that (e.g. how date_exceptions interacts with hours), so it sits just above 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?

Opens with a specific verb+resource (set the calendar) and immediately scopes it to two distinct targets: the business's calendar or a person's own booking page. It enumerates the fields under management (name, address, time zone, hours, date exceptions, reminders, confirmation calls) and explicitly names the sibling calendar_save_meeting_type as the next step, so an agent can place it 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 first call creates the calendar; then add meeting types with calendar_save_meeting_type" gives a clear create-then-extend workflow, and "Only the fields you pass change" tells the agent this is safe to call repeatedly for partial updates. The person parameter explains the alternative target. It stops short of explicitly routing reads to calendar_get_setup (that only appears inside the connected_calendar_id schema description), so the when-not is implied rather than stated.

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