Avlira Back Office

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the payload is informational (product, pricing, onboarding) but says nothing about whether the content is static or workspace-specific, or how large the response is. Useful but not rich beyond the annotations.

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

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

Two short sentences, zero filler, with the content scope front-loaded and the invocation trigger second. Every clause earns its place.

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

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

For a zero-parameter, read-only info tool with annotations covering safety and no output schema, the description tells the agent what it will learn and when to call it. Only minor gaps remain, such as whether the pricing/onboarding content is generic or tailored to the current workspace.

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 no parameter meaning to convey; the baseline for a parameterless tool applies. Nothing in the description misleads about inputs.

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

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

The description names the specific content the tool returns: what Avlira Back Office is, its cost, and how to get started. That is more concrete than a tautology like 'about Avlira', though it never states a verb (retrieve/explain) and doesn't explicitly distinguish itself from siblings such as get_help or get_started.

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

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

'Call this first when someone asks about Avlira' gives an explicit trigger condition and even an ordering preference, which is strong guidance. It stops short of exclusions — it doesn't say when to prefer get_started, get_help, or contact_avlira_support instead.

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 a non-destructive, closed-world write. The description adds the genuinely non-obvious behavior that no message is sent to the added agent, which affects follow-up actions. It stops short of covering error conditions or what the response contains.

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

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

Two short sentences, nothing wasted. Leading with the parenthetical prerequisite is slightly awkward ordering but front-loads critical context.

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

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

For a six-parameter create tool whose schema documents every field and whose annotations carry the safety profile, the description covers the prerequisite and the key side effect. Minor gaps remain around duplicates and failure behavior, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, with defaults and formats already documented for plan, join_date, and email. The description adds only the workspace_key prerequisite, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Add one agent to the roster.' The 'one agent' phrasing implicitly distinguishes it from bulk roster tools such as import_roster_csv, though it never names 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 a real prerequisite ('Needs the workspace_key from create_workspace') and notes the side effect that no message is sent. It does not say when to choose this over bulk-import or invite-style alternatives, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false; the description adds real value beyond them by disclosing the actual side effects — the deal is booked into the ledger and consumes the agent's cap, while no money moves. It does not cover edge behavior such as what happens if the deal is already approved or whether approval can be reversed.

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 clauses totaling roughly 25 words, with the prerequisite front-loaded in parentheses and the effect stated immediately after the verb. Nothing is padded and every clause carries information the agent needs.

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

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

For a two-parameter mutation with annotations and no output schema, the description covers prerequisite, effect, and authorization condition, which is enough to call it correctly. The remaining gap is failure/idempotency behavior on an already-booked deal, which matters given the ledger and cap 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?

Schema description coverage is 100%, so both parameters are already documented, and the description's note about workspace_key largely repeats the schema and the prerequisite framing. The only added nuance is that the deal must be 'pending', which implicitly constrains deal_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Approve a pending deal') and adds a clarifying consequence clause: it books the deal in the ledger and the agent's cap but 'pays nothing', which separates it from payment/commission tools. It stops short of naming which sibling to use instead of approving, 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?

Gives an explicit gating condition ('Only when the owner asked') and a prerequisite ('Needs the workspace_key from create_workspace'), which tells the agent both when and how it becomes callable. It does not name an alternative action for the case where the owner has not asked, leaving that inference to the agent.

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

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

Annotations say destructiveHint=false and readOnlyHint=false, but the description adds real behavioral context beyond them: the operation is refused when agents are still on the plan, and the refusal names those agents. That is genuinely useful pre-call information 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?

Two short sentences, front-loaded with the prerequisite, then the action, then the failure condition. No wasted text, though the parenthetical prerequisite opening slightly buries the actual verb.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the definition covers prerequisites, the action, and the blocking condition. It does not say what happens after archiving (e.g., whether the plan can be restored), but nothing essential to invoking it is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description only adds the provenance constraint that workspace_key comes from create_workspace. Baseline 3 is appropriate since the schema carries the parameter detail.

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?

"Retire a plan nobody uses any more" states a specific verb (retire/archive) and resource (plan). It distinguishes the operation from siblings like update_plan or list_plans, though it never explicitly names an alternative tool for the delete/update case.

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: use this to retire an unused plan, and it will be refused while agents remain assigned. There is no explicit guidance on when to prefer update_plan instead, nor on prerequisite ordering beyond the workspace_key parenthetical.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds a meaningful guarantee beyond them: earlier deals are unchanged, so the assignment is forward-only from the effective date. It does not cover idempotency or what happens when an agent is already on a plan, but the added non-retroactivity detail is real value.

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

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

Two tight sentences with no filler; the prerequisite, scope rules, and non-retroactivity each appear once. The leading parenthetical prerequisite pushes the actual purpose into second position, which is a minor structural weakness.

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 four-parameter mutation with full schema coverage and present annotations, the description supplies the prerequisite, the default date, and the non-retroactive scope. No output schema exists, but the description does not explain what is returned or how partial failures are reported, leaving a small gap.

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

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

Schema description coverage is 100%, so agents, plan_id, workspace_key, and effective_from are already documented, including the 'all' token and the YYYY-MM-DD default. The description only restates the accepted shapes and adds no format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: put agents on a plan, with the scope made explicit (one agent, a list, or 'all') and a start date. It is clearly a write/assignment operation and distinguishable from plan-creation siblings, though it never names an alternative tool.

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

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

Gives a concrete prerequisite (workspace_key from create_workspace) and the default behavior for the start date, which tells the agent how to call it correctly. It does not state when to prefer this over create_plan/update_plan or what to do if the agent list is invalid.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description only needs to add context. It contributes that the tool is free and computes to the cent, but with no output schema present it should describe the shape of the returned breakdown and does not. It also says nothing about the cap interaction behavior when cap_paid_so_far exceeds cap_cents.

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

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

Two sentences, front-loaded with the purpose before the input requirements, and no filler. The second sentence is long but each clause maps to a distinct parameter group, so it earns its length.

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

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

For an eight-parameter tool with zero required parameters, the description never explains what happens if the caller supplies nothing, nor which combinations are valid (gci versus sale_price plus commission_pct). With no output schema, the return value is only loosely gestured at as 'to the cent'. Adequate but with clear gaps for a calculation tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including the cents units and the 'agent first' split ordering. The description restates the parameter set in prose ('split (like 70/30, agent first), an annual cap, how much of the cap is already paid, a per-deal fee and a referral percent') without adding constraints such as valid split formats or behavior when split sums to something other than 100. This is the expected baseline when the schema does the heavy lifting.

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

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

The description names a specific verb and resource — a commission calculator computing what the agent and brokerage each receive from a closed deal — which is far more concrete than the title alone. It does not distinguish itself from the sibling 'commission_preview', leaving the agent to infer the difference between the two, so it stops short of a 5.

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

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

Usage is implied rather than stated: the description tells the caller to 'Give the sale price and commission percent (or the gross commission in dollars)', which frames the two input modes but never says when to choose this tool over commission_preview or record_deal. There are no explicit when-not conditions or prerequisite notes.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'without writing anything' largely restates structured data. The one genuinely additive detail is the cross-tool dependency on create_workspace, which the annotations do not convey; nothing is said about how the cap or company dollar is derived or whether workspace settings drive the split.

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

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

Two tight sentences with no filler. The prerequisite is placed in a leading parenthetical, which delays the actual purpose statement slightly, but the overall length is well matched to the content.

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

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

With no output schema, the description usefully names the three returned figures, which is the main gap it fills. For a 10-parameter tool it still leaves open how the split is computed (cap source, referral interaction) and what happens when required inputs are incomplete, so 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?

Schema description coverage is 100%, including the gci-vs-price+commission_pct alternative and the side aliases, so the schema already carries full parameter meaning. The description adds no additional semantics about how the 10 parameters interact, which is the correct baseline for a fully documented schema.

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

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

States a specific verb and resource ('Show how a deal would split') and enumerates the outputs (agent net, company dollar, cap), which is far more informative than the name alone. It doesn't explicitly distinguish itself from the sibling commission_calculator, so an agent must infer the preview-vs-calculator boundary.

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

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

The description gives a hard prerequisite ('Needs the workspace_key from create_workspace') but no explicit when-to-use versus when-not guidance. The preview framing implies it should be run before a real deal is recorded, but that routing to record_deal or commission_calculator 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 mark it non-read-only, non-destructive, non-open-world, so the safety profile is already covered; the description adds the prerequisite workspace_key and, importantly, the communication constraint "Never promise a response time" — behavior the agent would otherwise plausibly get wrong. It stops short of saying what happens after submission (ticket confirmation, whether the user sees a copy), which is the remaining gap.

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

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

Three short sentences, prerequisite first, then escalation rules, then the response-time caution — well front-loaded with no filler. The telegraphic fragment style is dense but readable; a slightly more connected phrasing would read better without adding length.

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

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

For a five-parameter, no-output-schema submission tool, the definition covers the prerequisite, the escalation gate, and a key agent-behavior constraint, which is most of what matters. What it lacks is any indication of what the caller gets back or what happens to the ticket afterward.

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

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

Schema coverage is 100%, so every parameter including urgency and details is already documented in structured data. The description only restates the workspace_key dependency and loosely gestures at urgency via the money/data trigger, adding little meaning beyond the schema — baseline 3 applies.

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

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

"Send a support ticket to the people at Avlira" gives a concrete verb plus destination, and the surrounding sentences distinguish it from get_help and diagnose, which are named directly. An agent can tell this is the human-escalation channel rather than a self-service help lookup.

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

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

It states both the exclusion (ONLY when get_help and diagnose did not solve it) and the qualifying triggers (suspected bug, money/data looks wrong, owner asks for a human). Alternative tools are named explicitly, which is exactly the routing information an agent needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write-without-destruction profile is covered. The description adds the meaningful model that a plan is either a flat fee, a split with an annual cap, or a combination — but says nothing about duplicate plans, validation failures, or what is returned on success.

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

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

Two compact sentences with no filler; the prerequisite is front-loaded and the entity definition follows. The leading parenthetical is slightly awkward but costs almost nothing and conveys required context.

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

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

For a 9-parameter mutation tool with no output schema, the definition covers the prerequisite and the conceptual shape of the entity but leaves the interplay among kind, split percentages, caps and fees to the schema. Adequate to call it correctly, thin on what happens afterwards.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, setting a baseline of 3. The description adds only modest semantic glue by grouping 'flat_dues' with the monthly fee and 'split_cap' with the annual cap; it doesn't clarify how kind, transaction_fee_usd and post_cap_transaction_fee_usd interact, which is the genuinely ambiguous part of a 9-parameter 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?

Names a specific verb and resource ('Create a commission plan') and goes further by defining the domain object itself: a flat monthly fee and/or a split with an annual cap. An agent can distinguish this from update_plan/assign_plan/list_plans by the verb, though the description doesn't explicitly say so.

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 lead parenthetical states the prerequisite that workspace_key must come from create_workspace, which is real ordering guidance an agent needs before calling. It stops short of exclusions or pointing to update_plan for modifying an existing plan, so it's clear context rather than full when/when-not guidance.

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

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

Beyond the annotations, the description explains that this creates real data, returns a one-time owner sign-in link and an owner AI key shown once, and includes the free plan limit. Those details materially inform the agent about side effects, secret handling, and non-idempotent behavior. The caution against repeated calls is especially valuable for a creation 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?

The description is front-loaded with the core action and scope, then moves to outputs, prerequisites, and the one-time warning. Every sentence carries operational value, and there is no filler or repetition.

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

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

For a creation tool with no output schema, the description covers the important gaps: required user input, returned URLs and credentials, plan limits, and the risk of duplicate calls. It stops short of explaining error cases or what happens if a workspace already exists, but the essential calling 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?

The schema already has 100% description coverage for all five parameters, including brokerage_name, owner_name, owner_email, state, and agent_count. The description reinforces the three required inputs by telling the agent to collect them first, but it does not add syntax, format, or meaning beyond the schema. Baseline 3 is appropriate when the schema carries parameter semantics.

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

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

The description opens with a specific verb and resource: 'Create a new private Avlira Back Office workspace for a brokerage.' It also names the plan constraints and returned artifacts, making the tool's purpose unmistakable without requiring the schema. No sibling tool creates a workspace, so the action is clearly singular.

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

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

It gives concrete pre-call guidance: 'Ask the user for the brokerage name, their name and email first.' It also warns 'call it once, not repeatedly,' which is useful when-to-use and when-not-to-repeat guidance. It does not explicitly name an alternative tool, but no sibling offers workspace creation, so the omission is minor.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still adds useful behavior: the create_workspace prerequisite for the key and the fact that output is plain-English with a ranked set of top 3 next actions. It adds moderate context beyond annotations but says nothing about cost, freshness, or how missing data is represented.

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?

Compact: two sentences, one covering the prerequisite and one covering scope, with the enumerated checks front-loaded so an agent can scan them. The leading parenthetical prerequisite is slightly awkward placement, but nothing is padding.

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

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

With no output schema, the description must carry the return shape, and it does so only at a topic level (what categories are checked, plus the top 3 next actions) without stating format or structure. The prerequisite and sequencing are covered, so an agent can call it correctly, but it cannot anticipate what the response will look like.

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

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

Schema coverage is 100% and the single parameter's schema description already states it is the key returned by create_workspace; the description's parenthetical repeats rather than extends that. With one fully documented parameter, the baseline of 3 is met and the explicit tie to create_workspace reinforces the prerequisite, but no new meaning is added.

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

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

States a specific action (plain-English health check) on a specific resource (THIS back office) and enumerates exactly what is inspected: plan and limits, agents missing email or mobile, pending deals, unpaid dues, W-9s, email verification, connected AIs, top 3 next actions. This clearly differentiates it from narrow siblings like unpaid_dues or today, which cover only one slice.

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

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

Gives real sequencing guidance: run it after get_help, and it requires a workspace_key from create_workspace, which frames it as an early onboarding step. It does not explicitly say when to prefer narrower siblings (e.g., unpaid_dues) or when this would be redundant, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: the data comes from a weekly refreshed public file (implying staleness up to a week), only public fields are returned, and name searches are capped at 10 matches — none of which is in the annotations or schema.

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

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

Two compact sentences, front-loading the capability and source before the lookup modes, then the return fields. Every clause contributes information; there is no filler or restatement of the name.

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

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

With no output schema, the description helpfully enumerates the returned fields and signals the data source's weekly cadence. The only gap is behavior when both optional parameters are omitted or combined, which an agent would need to know for a zero-required-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: license_number is an exact match (no fuzzy/partial) while name matches partially and is limited to 10 results. That exact-versus-partial contrast and the result cap are not expressed by the parameter descriptions alone.

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 (look up a Florida real-estate licensee) plus the exact data source (public DBPR weekly file) and the two supported search modes. The returned field list makes the scope unambiguous and no sibling tool overlaps with it.

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

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

The description clearly indicates when each input mode applies: exact license number lookup versus name search with a cap of 10 matches. It does not state what happens if both parameters are supplied, nor does it name any alternative tool, leaving that edge case to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one piece of behavior beyond that: the response also reveals plan-allowed changes, not just current appearance. It says nothing about authorization or failure modes, so the added value is modest.

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

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

Two short sentences, prerequisite front-loaded, then purpose with concrete field examples. No filler, though the parenthetical-first ordering slightly buries the primary action.

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

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

With no output schema, the description usefully previews what comes back (display name, colors, tagline, logo, plus plan-allowed changes), which is exactly what an agent needs before calling. Only the plan-entitlement portion is left vague.

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

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

Schema coverage is 100% and the single parameter is already documented as 'the workspace_key returned by create_workspace'. The description restates that same origin rather than adding format or validation detail, so the schema does the heavy lifting and 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 a specific verb ('Read') and resource ('the back office' branding) and enumerates the fields returned (display name, colors, tagline, logo). It is clearly distinguishable from update_branding/reset_branding by its read framing, though no sibling is named explicitly.

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

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

It supplies a real precondition ('Needs the workspace_key from create_workspace'), which is genuine usage guidance, and the phrase 'what the plan allows to change' implies reading before editing. However it never states when to use update_branding instead, nor any exclusion.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description reinforces the closed-corpus nature ('built-in help') and notes the workspace_key prerequisite, but says nothing about what happens when no answer is found or whether it escalates.

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 with no filler, and the prerequisite is front-loaded in parentheses. The parenthetical placement is slightly awkward but costs nothing in 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 two-parameter read-only lookup with no output schema, the definition covers purpose, prerequisite, topic scope, and call priority. Only the unanswered-question behavior is left unstated.

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 a topic taxonomy (sign-in trouble, plans, deals, dues, 1099s, AI connection, branding) that gives concrete guidance on how to phrase the 'question' parameter beyond the schema's generic 'what went wrong'.

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 — 'answers from the built-in help for a question' — and enumerates concrete topics (sign-in, plans, deals, dues, 1099s, AI connection, branding). It does not explicitly differentiate itself from close siblings like about_avlira, get_started, or contact_avlira_support, so it stops short of a 5.

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

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

'Try this FIRST when the owner is stuck' gives explicit ordering guidance that implicitly positions it ahead of contact_avlira_support. It lacks an explicit when-not clause or a named escalation path for unanswered questions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds that this returns guidance content rather than mutating anything, and supplies the sequencing constraint. The only shortfall is that it does not say whether the script is static or tailored to the current workspace state.

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

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

Two sentences, zero filler. The content description comes first and the sequencing instruction second, so the most actionable guidance is front-loaded.

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

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

For a zero-parameter, read-only guidance tool with no output schema, the description covers what comes back and when to invoke it. It stops short of clarifying whether the script adapts to the existing workspace or is fixed content, a minor gap given the tool's simplicity.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly implies no inputs are needed by framing it as a script to be read.

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 concretely: a plain-English setup script covering 'what to ask, in what order' for a non-technical brokerage owner. That is far more specific than the bare name get_started, and it is clearly differentiated from create_workspace and about_avlira, though it is phrased as a noun phrase rather than an explicit verb+resource.

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

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

It states precisely when to call it — 'right after about_avlira, before create_workspace' — which pins down its position in the onboarding sequence and implicitly excludes calling it mid-setup or standalone. An agent needs no inference to place this call 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 declare a non-read-only, non-destructive, closed-world mutation, and the description adds a prerequisite credential source and a safety workflow (dry run, owner review) that goes beyond those hints. It stops short of disclosing what happens on duplicates, invalid rows, partial failures, or whether an import is reversible.

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

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

Three sentences, with the credential prerequisite leading and the mandatory workflow last, so the two things an agent must know before calling are front- and back-loaded around the CSV format. No redundant restatement of the title or schema.

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

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

Covers prerequisites, CSV shape, and the required invocation sequence for a 4-parameter mutation tool with no output schema. The remaining gap is that it tells the agent to 'show the owner the result' without characterizing the dry-run output or error reporting, which matters since no output schema exists.

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 would be 3, but the description adds real meaning the schema lacks: the required vs optional CSV columns inside csv_text, and the operational contract for dry_run (check first, then import). It does not explain default_plan, though the schema already documents it.

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

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

States a specific verb and resource ('Import agents from a roster CSV') plus the exact expected CSV columns, including which are optional. The bulk-CSV framing distinguishes it from the single-agent sibling add_agent without needing to name it.

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 prerequisite ('Needs the workspace_key from create_workspace') and a mandatory two-step protocol: always dry_run=true first, show the owner the result, only then dry_run=false. That is a clear when/how-to-use procedure, not an implied one.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds that the result is unfiltered (every agent) and includes plan and status, but says nothing about ordering, pagination, or behavior when the workspace has no agents.

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 waste; the prerequisite is placed first and the output summary second. The parenthetical phrasing is slightly awkward but not verbose.

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

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

For a simple one-parameter read tool with annotations covering safety and a fully documented schema, the description covers scope, returned fields, and the key prerequisite. Remaining gaps (ordering, empty-result behavior) are minor for a tool of this complexity.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description's note that workspace_key comes from create_workspace largely repeats what the schema already says, adding no new syntax or format detail.

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?

"Every agent on the roster with plan and status" states the resource (agents) and the fields returned, and the tool name supplies the list verb. It is clear what the tool produces, though it does not distinguish itself from siblings like add_agent or import_roster_csv.

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

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

The description gives a prerequisite (needs workspace_key from create_workspace) but no guidance on when to choose this tool versus related roster tools such as add_agent or import_roster_csv. Usage is only inferable from the name and the word "roster."

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

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

Annotations already declare this is a safe, non-destructive, closed-world read, so the bar is lower. The description still adds useful behavior: the cross-tool dependency on create_workspace and a concrete inventory of the returned template categories plus merge fields, which is substantive 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?

One sentence, no filler, with the prerequisite front-loaded in parentheses so it is read before the call is attempted. The enumerated categories make the sentence longer but each item carries information about what is returned; a slight structural wart is mixing the prerequisite with the content description in the same breath.

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

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

For a one-parameter read with no output schema, the description covers the prerequisite, the scope of returned templates, and the presence of merge fields — enough to call it correctly and know what to expect. The absence of an output schema means slightly more detail on response shape would have been welcome, but nothing essential is missing.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already explains workspace_key fully. The description only repeats the dependency on create_workspace, adding no new syntax or formatting detail — exactly the baseline case where the schema does the lifting.

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

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

States a specific read action and enumerates exactly what is returned: the wording for the reminder stages (friendly, followup, final, card_expired, no_card), the onboarding invite text, and merge fields. That is far more specific than 'list templates' and implicitly contrasts with the update/reset siblings by being a read. It stops short of naming those siblings explicitly.

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

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

The parenthetical supplies a real prerequisite — the workspace_key must come from create_workspace — which tells the agent when the tool can be called. However, there is no explicit when-to-use guidance or statement of the alternative (e.g., use update_message_template to change wording rather than read it); that has to be inferred from the sibling names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the dependency that callers must first obtain a workspace via create_workspace, which is genuinely useful context beyond the annotations, but it says nothing about result volume, ordering, or whether all plans in the workspace are returned.

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

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

Two very short segments with zero waste, and the prerequisite is front-loaded before the purpose statement. The second sentence is a fragment ('The commission plans agents can be on') that reads slightly awkwardly, but nothing is padded.

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

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

For a read-only single-parameter list tool with no output schema, the definition covers purpose and the prerequisite workspace dependency. It leaves ambiguous whether it returns all plans or only active ones and whether pagination applies, which matters for an agent deciding whether to call it before assign_plan.

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

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

Schema coverage is 100% and the single workspace_key parameter is already documented as 'The workspace_key returned by create_workspace' — nearly identical wording to the description's parenthetical. The description therefore adds essentially no meaning beyond the schema; baseline 3 is appropriate.

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

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

The description identifies the resource specifically — 'the commission plans agents can be on' — which is distinct from create_plan, update_plan, archive_plan, and assign_plan by way of the list_ prefix. It stops short of an explicit verb like 'list all', relying on the tool name to carry that half of the meaning, so it is clear but not fully self-contained.

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 parenthetical supplies a real usage prerequisite: workspace_key must come from create_workspace first. However, there is no guidance on when to call this versus the other plan-related siblings (create_plan, assign_plan) or other list tools — usage is implied by the name rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety profile is largely covered. The description adds real value beyond that by disclosing the PENDING initial state, the no-payment outcome, and the prerequisite workspace_key — but says nothing about idempotency, duplicate handling, or what happens to later approval.

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

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

Two short sentences with the prerequisite front-loaded in parentheses and the outcome/approval path following. Every clause carries information; nothing is redundant 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 10-parameter mutation with no output schema, the description covers lifecycle and the external approval gate but omits what the call returns (e.g., whether a deal id is produced and needed for approve_deal). Adequate to call it correctly, but incomplete about the handoff to the approval step.

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%, including the workspace_key provenance note, so the schema carries parameter semantics fully. The description repeats the workspace_key dependency but adds no meaning about the other nine fields (gci vs price+commission_pct, side normalization, referral fields), 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 states a specific action and resource — enter a closed or closing deal, created in PENDING state — and implicitly separates it from the approval step by naming approve_deal. It stops just short of a crisp verb+resource framing ("record a deal"), but an agent can still tell this apart from approve_deal 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?

It gives a clear usage context: the deal must be closed or closing, it lands as PENDING, nothing is paid, and the owner approves it in the app or via approve_deal. That effectively routes approval away from this tool, though it does not explicitly state when not to use it (e.g., for already-approved or paid deals).

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 description usefully discloses what is lost — custom colors, name, tagline and logo — which goes beyond the annotations. However, it sits in mild tension with destructiveHint=false, and it never says whether the removed branding is recoverable or how to restore it. No return-value behavior is described either, though no output schema exists.

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

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

Two compact sentences with no filler; the prerequisite is front-loaded before the effect. Slightly awkward that the prerequisite sits in parentheses ahead of the primary action, but nothing is wasted.

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

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

For a single-parameter mutation with annotations present and no output schema, the definition covers the prerequisite, the scope of the reset, and the affected fields. Only edge-case behavior (workspace with no custom branding, reversibility) is left unstated, which is a minor gap.

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

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

With one parameter at 100% schema coverage, the schema already documents workspace_key fully. The description restates the same provenance detail rather than adding format, validation, or failure semantics, so the baseline of 3 applies.

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

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

"Put the look back to the Avlira defaults" is a concrete verb+resource, and the parenthetical enumerates exactly which customizations are cleared (colors, name, tagline, logo). It is clearly distinct from the adjacent get_branding/update_branding capabilities, though those siblings are not named.

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 parenthetical states the prerequisite (needs workspace_key from create_workspace) and the effect implies the use case — reverting a customized workspace. There is no explicit when-not guidance, e.g. that partial changes should go through update_branding instead of a full reset.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description's "put back to default" is consistent with a non-read mutation, so no contradiction. However, it never says whether the existing custom wording is permanently lost or recoverable, which is the single most important behavioral fact for a reset operation.

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

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

Two short sentences with no filler, and the prerequisite is front-loaded in a parenthetical before the action statement. It is efficient, though the parenthetical placement slightly buries the actual purpose behind setup detail.

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

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

For a two-parameter tool with no output schema, the description covers the prerequisite and the effect but omits what the call returns and whether the reset is reversible. Annotations cover the safety profile, so the remaining gaps are moderate rather than critical.

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

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

Schema coverage is 100%, so both parameters are already documented, including the create_workspace provenance of workspace_key. The description only reinforces that a single template (the `kind`) is affected and does not explain what values `kind` accepts beyond "Which template."

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?

"Put one reminder wording back to the Avlira default" gives a specific verb (reset to default) and a specific resource (a single reminder template wording), which implicitly separates it from update_message_template. It stops short of naming that sibling, so an agent must infer the contrast from the phrase "back to the Avlira default."

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

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

The description supplies a prerequisite ("Needs the workspace_key from create_workspace") but no explicit when-to-use versus update_message_template, which is the obvious alternative for changing wording. Usage is only implied: revert rather than customize.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the result aggregates several heterogeneous categories of pending/attention items, but says nothing about whether these are counts, lists, or how much detail is returned — a real gap since there is no output schema.

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

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

Two compact clauses: the prerequisite is front-loaded, then the payload is enumerated in a single list. "and other items needing attention" is slightly vague filler but overall there is little waste.

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

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

For a one-parameter read-only summary tool with no output schema, the description gives enough shape (which categories of information come back, where the key comes from) to call it correctly. Return-value detail is thin, but the enumerated categories do most of the work an output schema would otherwise do.

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

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

Schema coverage is 100% and the single parameter is documented in the schema as "the workspace_key returned by create_workspace"; the description's parenthetical restates that same fact rather than adding new meaning. Baseline 3 is appropriate when the schema already carries all parameter information.

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 concrete contents — pay-day status, dues, deals awaiting approval, onboarding — so an agent understands this is an aggregate daily-status/dashboard resource. The verb is only implied ("Today's picture"), which keeps it short of a fully specified verb+resource phrasing, but the scope is distinguishable from narrower siblings like unpaid_dues.

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 prerequisite (needs workspace_key from create_workspace) is stated, and the enumerated categories hint that this is the orientation/summary entry point. However, there is no explicit statement of when to call this versus drilling into a specific sibling such as unpaid_dues or approve_deal, and 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the dependency chain (obtain workspace_key via create_workspace) and the month-scoping behavior, but says nothing about return shape, sorting, or what 'why' actually surfaces. That is adequate-but-thin given the annotation coverage.

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

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

Two compact sentences with no filler, and the blocking prerequisite is placed first so an agent sees it before anything else. The parenthetical packaging is slightly awkward but nothing is wasted.

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

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

For a read-only, two-parameter query with no output schema, the description leaves the return value entirely unspecified — an agent cannot tell whether 'why' means a reason field, a note, or a failure code. The prerequisite and scope are covered, but the missing output expectation is a real gap.

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

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

Schema coverage is 100%, and the schema itself documents both parameters including the 'YYYY-MM (default this month)' format for month. The description only restates the workspace_key prerequisite, adding no new meaning about the month parameter or its defaulting behavior. Baseline 3 applies when the schema carries the load.

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

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

The phrase 'Who has not paid this month's dues, and why' clearly identifies the resource (unpaid dues for the current month) and implies the result includes a reason. It is phrased as a question rather than a verb+resource, and it names no sibling to differentiate from, so it falls short of a 5.

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

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

The only contextual guidance is the parenthetical prerequisite that a workspace_key from create_workspace is required. There is no statement of when to reach for this tool versus list_agents or today, and no exclusions or alternatives are offered.

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 (readOnlyHint=false, destructiveHint=false) the description discloses real behavior: colors must be #RRGGBB, too-light colors are rejected with a suggested alternative, logo must be https png/svg/webp under 512 KB, and the logo_url field doubles as a removal mechanism via empty string. The Free/Pro entitlement gating is behavioral information an agent could not get from the schema or 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?

The prerequisite is front-loaded in parentheses and every subsequent sentence carries a distinct constraint (validation, entitlement, format). The style is telegraphic and dense — the Free/Pro list reads as shorthand rather than prose — 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 7-parameter mutation with no output schema, the description covers prerequisites, validation rules, and entitlement limits, which is most of what an agent needs. It omits partial-update semantics and whether the call returns the resulting branding, leaving a small but real gap for a write operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema does not carry: it partitions the parameters into Free (display name, colors, tagline) and Pro (logo_url, login_message), which changes what an agent should attempt to set. It does not address whether omitted fields are left untouched or cleared, which is the remaining semantic 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?

"Change how the back office looks" plus an explicit field inventory (display name, colors, tagline, logo_url, login_message) makes the resource and effect clear. It never names get_branding or reset_branding, so the agent must infer that this is the write counterpart, but the purpose itself is unambiguous.

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

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

It states the prerequisite ("Needs the workspace_key from create_workspace") and a workflow rule ("Confirm colors with the owner in plain words first"), plus a Free vs Pro split that tells the agent which fields are even available. It stops short of naming an alternative such as get_branding for reading or reset_branding for reverting, so there is no explicit when-not guidance.

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

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

Annotations only declare it as a non-read-only, non-destructive, closed-world mutation; the description adds real behavioral content on top: a 480-character cap for texts, the requirement to preserve {pay_link} where the default has it, and the 'show the owner first' confirmation step. It does not describe what the call returns or what happens if constraints are violated, keeping it below 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?

The prerequisite is front-loaded and every clause carries information; nothing is padding. However the merge-field inventory is written as an unpunctuated run of tokens with a parenthetical invite exception, which is dense enough to risk misparsing compared with a short list format.

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 5-parameter mutation with no output schema, the description covers the prerequisite, content constraints, kind/channel coupling, and the review step, which is most of what an agent needs to call it correctly. Minor omissions remain around failure behavior and the optional subject field for email templates.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: it maps kind values to channel ('final is email, the rest text'), constrains body length and required placeholders, and lists which merge fields each template kind may use. That goes meaningfully beyond the schema's generic strings.

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

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

The description uses a specific verb ('Reword') on a clearly scoped resource ('a collection reminder or the onboarding invite') and enumerates the template kinds. It is easy to separate from list_message_templates or reset_message_template by intent, though it never names those siblings to make the distinction 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?

It gives a concrete precondition ('Needs the workspace_key from create_workspace') and a workflow rule ('Show the owner the wording first'), which tells the agent not to just apply the change blindly. There is no explicit when-not guidance or pointer to reset_message_template for reverting, so it falls short of full alternative routing.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavior: partial update semantics ('only what you pass changes') and, critically, the temporal scoping rule that only FUTURE deals use new terms while booked deals keep their numbers. That forward-only effect is exactly the kind of consequence an agent must know before mutating a plan. It does not cover permissions or error behavior.

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

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

Four short sentences, prerequisite front-loaded in parentheses, then purpose, then the most consequential behavior (future-only effect), then a one-line clarification. No filler; every sentence carries information.

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

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

For an 11-parameter mutation tool with full schema coverage and no output schema, the description covers the prerequisite, partial-update behavior, and downstream effect on deals. The reliance on 'same fields as create_plan' means an agent must cross-reference another tool for field meaning, a minor but real 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 baseline is 3, but the description adds real meaning beyond the schema: partial-update semantics ('only what you pass changes') and a pointer to create_plan for field definitions. The 'remove_cap true = no cap' line largely restates the schema's own description, so it adds little.

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 ('Change') and resource ('an existing commission plan') and explicitly contrasts with create_plan by noting it takes the same fields. An agent can distinguish this from create_plan and archive_plan without opening schemas, though the 'same fields as create_plan' phrasing defers some meaning to a sibling.

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

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

Gives a clear prerequisite ('Needs the workspace_key from create_workspace') and implies use for modifying rather than creating plans. It does not explicitly say when to use archive_plan instead, nor what happens if a field is omitted beyond the partial-update note.

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 carry the safety profile (readOnly, non-destructive, closed-world), and the description repeats read-only while adding the useful returned data fields. It does not discuss permissions beyond the workspace_key prerequisite, error behavior, or freshness of counts, so it adds some but not rich behavioral context.

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

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

The definition is two compact sentences with the prerequisite front-loaded and the return scope stated directly. There is no redundant or filler text, and it is appropriately sized for a simple read tool.

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

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

For a one-parameter read-only tool with annotations and no output schema, the description provides the prerequisite and enumerates the main returned fields. It could go slightly further on what the counts represent or what happens with an invalid key, but it is largely complete.

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

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

Schema coverage is 100% and the single workspace_key parameter is fully described in the schema. The description restates the prerequisite without adding format, validation, or alternative meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies a read-only retrieval of workspace/brokerage settings and enumerates the returned fields (name, URLs, plan, owners, counts). It does not use a direct verb or explicitly distinguish this from siblings, but the resource and scope are clear.

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

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

The only guidance is the prerequisite that workspace_key comes from create_workspace. There is no explicit when-to-use guidance, no comparison to alternatives such as get_branding or about_avlira, and no exclusions.

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