ISMS Copilot

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the human-in-the-loop payment requirement, that nothing is charged without browser payment, the fixed return URL host, a 5-per-hour-per-user rate limit, and the required api_credits:checkout scope. These are exactly the operational facts an agent cannot derive from structured fields.

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

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

Five short sentences, each carrying a distinct fact: what it creates, when to use it, that payment is human-gated, the follow-up poll, and the constraints (redirect host, rate limit, scope). The critical action and constraint lead.

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

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

Despite having no output schema, the description tells the agent what the return value is (a checkout URL), what happens after (human pays, then poll get_api_credit_balance), and the full constraint envelope. An agent has everything needed to call this correctly and safely in a single pass.

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

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

Schema description coverage is 100% and the single 'amount' parameter is already documented with type, min 20, and max 10000. The description's '(min $20)' merely restates the schema rather than adding new meaning such as currency assumptions or rounding 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 — 'Create a Stripe Checkout URL' for 'prepaid model API credits' — with the amount constraint ($20 min) right in the first sentence. This is clearly distinguishable from siblings like create_api_key or get_api_credit_balance.

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 user asks to add API credits') and an explicit follow-up action ('Then poll get_api_credit_balance'), effectively naming the alternative tool for the balance-reading case. Nothing about when to invoke this 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?

Discloses behavior an agent cannot get from annotations: the plaintext token is returned exactly once and must be handed to the user for secure storage, there is a 20-active-key cap, and the call requires the api_keys:write scope. These are precisely the failure modes (losing the token, hitting the quota, missing auth) that matter for this mutation.

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

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

Four short sentences, front-loaded with what the tool produces and the one-time-secret warning before the quota and permission notes. No filler.

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

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

With no output schema, the description still explains the return value (plaintext token, delivered once) and adds prerequisites and limits. An agent has everything needed to call this correctly and handle the result safely.

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

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

The single parameter is fully documented in the schema (label, max 80 chars) at 100% coverage, so the schema carries the load. The description adds no further semantics about the name field, which matches the baseline 3 for high-coverage schemas.

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

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

States a specific verb and resource ('Mint a new model API key'), plus the concrete token format, endpoint, and auth scheme. This is unmistakably distinct from siblings like create_api_credit_checkout or create_company.

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 constrains usage ('Use it only when the user asks for a new key') and rules out a likely confusion by noting it does not add prepaid credits. However, it never names the relevant alternatives (list_api_keys for inspection, revoke_api_key for cleanup), so routing is solid but not fully specified.

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, non-idempotent, non-destructive) by disclosing the auth scope 'company_context:write', the plan-based quota with a 429 that names the limit, and the non-obvious constraint that at least one of nine optional fields must be supplied. That last point is the key behavioral fact the schema cannot express, since required is empty.

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 definition, then trigger, then exclusion, then constraint, then auth. Every sentence carries information, though the field list and permission clause make it slightly dense as a single block rather than clearly separated.

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 create tool with nine optional string params and no output schema, the description covers trigger, exclusion, minimum-content rule, quota behavior, and required scope. Only the success return (e.g. whether a company id is returned for chaining into link_company_to_workspace) 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 real semantic content: it enumerates the accepted fields and spells out the closed value set for privacy_role (controller|processor|both), which the schema states only in prose. It does not add format guidance, but the coverage gap is small.

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

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

States a specific verb+resource ('Create a company') and defines it functionally as 'a company item workspaces link to'. It explicitly names the two nearest siblings (link_company_to_workspace, update_company) so an agent can distinguish create from link and from update without opening other schemas.

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

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

Gives an explicit trigger ('when the user adds a new client or company'), a follow-up action ('then link it with link_company_to_workspace'), and an explicit exclusion ('Do not use it to change an existing company (update_company)'). The when/when-not/alternative triad is fully covered.

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 limit/rate behaviour ('reset_at', reset guidance), paid-plan gating for 'think'/'beyond', the daily cap and the beyond_denied_reason fallback, the overflow behaviour on eligible accounts, the 'generating' status requiring a get_reply poll, that a limit error still returns a usable conversation_id, and that docgen_notice must be relayed. It also sets an explicit privacy boundary on what may not be 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?

Purpose is front-loaded and almost every sentence carries operational weight, but the text is long and has redundancy: the 'assistant' rule and the 'do not paste framework text' instruction are both restated in the schema descriptions, and the specialist bullet list is verbose. Nothing is misleading, but some compression is possible.

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, open-world, non-idempotent tool with no output schema, the description covers return shape (conversation_id, message_id, status), the polling path via get_reply, error and limit handling, and account gating. Combined with the schema it leaves nothing an agent needs before calling.

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?

Even at 100% schema coverage, the description adds real meaning: a routing rule for 'assistant' ('a task to do takes the job id even when it names a framework; a question about one framework takes that framework's id; else omit'), plus a per-specialist routing table and a note that the assistant persists for the conversation. It also explains 'beyond' versus 'think' beyond what the enum alone conveys.

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 ('Ask the ISMS Copilot GRC specialist and start a new conversation for one deliverable') and explicitly scopes it to a single deliverable, which separates it from send_message for follow-ups. The framing is unambiguous about what is being created and what it is for.

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 dense when-to-use list (clause questions, policy drafting, gap analysis, SoA justifications, incident response, etc.) plus explicit when-not-to-use conditions: code, git, files, questions with no compliance angle, and follow-ups on the same deliverable. It also names the alternative (send_message) for the follow-up case and tells the caller not to paste framework text.

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

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

Annotations already establish this is a non-read-only, non-idempotent, non-destructive write, and the description usefully explains why it is non-idempotent ("Each call adds a new memory") and adds a hard size constraint (500 chars). It does not cover what happens on failure or whether memories can be duplicated or capped, 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?

Four short sentences, front-loaded with the definition before the constraints and exclusions; the only mild repetition is the 500-character limit, which is reasonable to surface in prose because it is a hard authoring constraint.

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

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

For a two-parameter creation tool with no output schema and full schema coverage, the description supplies everything an agent needs: what a memory is, required size limit, scoping choice, and the routing rules to the two nearest alternatives.

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

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

Schema description coverage is 100% and both parameters are already documented there, including that workspace_id is a UUID from list_workspaces and that omitting it yields a personal memory. The description restates the personal-vs-workspace distinction but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Save a memory") and immediately defines what a memory is ("a short fact ISMS Copilot uses as background in later answers") plus its two scoping modes. It also names the sibling it is not — update_memory and set_company_context — so an agent can distinguish it from siblings without opening a schema.

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

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

It gives an explicit positive trigger ("only when the user asks ISMS Copilot to remember something") and two explicit exclusions with the correct alternative named for each (set_company_context for company facts, update_memory for edits). Nothing is left to inference about when to route elsewhere.

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 429 rate limit of 10 workspaces per 24 hours including web-app usage, the auth requirement (workspaces:write), that the workspace is not team-shared and does not inherit organization Advanced Data Protection, and that organization_id/persona inputs error out. The non-idempotency note is consistent with idempotentHint=false and clarifies the concrete consequence (two identical calls create two workspaces).

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?

Action and usage guidance are front-loaded, and each subsequent sentence carries a distinct operational fact (constraints, non-sharing, non-idempotency, rate limit, follow-up, scope). It is dense with clauses and could be split for readability, but nothing 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 one-parameter creation tool with no output schema, the description covers everything an agent needs: trigger conditions, exclusions, input limits, side effects, quota behavior, required scope, and how to find the created object 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% and the description's name constraints (trimmed, non-empty, max 120) restate the schema field verbatim. The added note that passing organization_id or persona returns an error is useful but behavioral rather than a clarification of the declared parameter, so this sits at the baseline.

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

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

States a specific verb and resource ('Create a new personal workspace owned by the token user') along with the key owning scope. It explicitly separates itself from adjacent operations (rename, share, persona/instructions) that are handled elsewhere, so an agent can distinguish it from update or team-sharing tools in the sibling list.

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 positive trigger ('when the user asks for a new workspace, for example for a new client') and explicit exclusions ('Do not use it to rename or share one'), naming the correct surface (web app) for those excluded cases. It also names the follow-up tool list_workspaces for verification.

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?

Even though annotations already mark this as destructive, idempotent, and not read-only, the description adds crucial domain behavior: linked workspaces are automatically unlinked and their data is never deleted. It also states the required permission ('company_context:write'), which is not captured by 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 description is four tight sentences with no filler, and it leads with the core action before covering usage constraints, cascade behavior, and permissions. Every sentence carries operational 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 destructive, single-parameter tool with no output schema, the description covers the key risks and side effects: cascade unlinking, data preservation, permission requirements, and the alternative detachment tool. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, and the single parameter is documented in the schema as a UUID from list_companies. The description adds 'by id' but no additional format or sourcing detail 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 states a specific verb and resource ('Delete ... companies') and constrains it by id. It also explicitly distinguishes the operation from the sibling tool unlink_workspace_company, so an agent can identify the correct tool without opening sibling schemas.

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

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

It gives an explicit use condition ('only when the user asks to remove that client or company') and names the alternative tool for detaching a single workspace. The when-to-use and when-not-to-use guidance is clear and actionable.

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

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

Annotations already declare this a safe idempotent read, and the description still adds substantive behavior: what is NOT returned (live remaining quota), that Data Protection is read-only here with a redirect to the mutation path, and what limit errors from create_conversation/send_message contain (reset_at, upgrade_url, quota_scope, org_role, extra_usage_buyable) plus the 4-hour window.

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 returned fields, then usage guidance, then exclusions — a sound order with no filler. The final two sentences drift into the error contract of sibling tools (create_conversation, send_message), which is useful context but slightly beyond this tool's own scope.

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 compensates by enumerating the returned fields and their nested URL keys. An agent has everything needed to call it and interpret the result without opening anything else.

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 applies. The description correctly spends no words on input semantics and instead documents the output surface.

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 enumerates the exact resource contents returned (user id, scopes, Advanced Data Protection state, plan slug, owned chat-app URLs), so an agent knows precisely what it gets back. It also draws a boundary against the quota-checking siblings in the same breath.

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

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

Gives explicit triggers (user asks about plan or settings, or after a limit error to show where to check usage) and an explicit exclusion (do not call it to check remaining quota before a conversation). It also routes the agent to data_protection.manage_url for the mutation case.

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, so the safety profile is covered; the description adds the required scope (api_credits:read) and the interpretation rule that zero means top up. It does not mention any rate limits or whether the balance is cached/eventually consistent, so it falls just 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?

Four short sentences, front-loaded with the identity of the resource, followed by usage, edge-case handling, and the permission requirement. Nothing is redundant or 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?

With no parameters and no output schema, the description supplies everything needed: what is returned (a USD credit balance), how to read a zero result, and the scope requirement. An agent can invoke it correctly without further information.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. The '(USD)' qualifier usefully fixes the unit of the implicit return value.

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

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

States a specific verb and resource ('Read the prepaid model API credit balance (USD)') and clearly distinguishes it from the write-side sibling create_api_credit_checkout. An agent can tell immediately this is a read of a scalar balance, not a transaction.

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

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

Gives two concrete triggers ('when the user asks about API credits' and 'after a checkout to confirm the payment landed') and routes the zero-balance case explicitly to create_api_credit_checkout or the Credits page. When-to-use and what-to-do-next are both spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the required `company_context:read` scope and the shape of the returned record. It stops short of describing error behavior for an unknown id, which keeps it off a 5.

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

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

Two sentences, zero waste, with the core action and returned fields front-loaded before the conditional usage note. 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?

There is no output schema, but the description compensates by listing the returned fields (id, company_profile, created_at, updated_at). Combined with the stated auth scope and the id source, an agent has everything needed to call this 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 single parameter already documents that it is a UUID sourced from list_companies. The description's "by id (client context)" adds only marginal framing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Read one of your companies by id") and enumerates the returned fields, so the agent knows exactly what comes back. It also implicitly distinguishes itself from the list/browse and context siblings.

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

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

Gives an explicit precondition ("when you already have a company_id from list_companies or get_company_context") plus a named alternative for the other case ("to browse, use list_companies"). The required permission scope is stated outright, leaving nothing to inference.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the required scope (company_context:read), the return shape, the meaning of null, and the non-obvious consequence that turns in a workspace then use no company profile. The workspace-vs-account resolution rule is precisely the hidden behavior an agent would otherwise get wrong.

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

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

Front-loaded with the purpose in the first clause, then scope, then return contract, then usage caveats — a sensible order. It is dense but slightly redundant: the parenthetical about turns using no company profile repeats a point already implied by "null means not set."

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 only one optional parameter and no output schema, the description still supplies the return object shape, the null case, the auth scope, and the fallback-resolution behavior. An agent can call this confidently on the first try and correctly decide not 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 coverage is already 100%, so baseline is 3; the description earns above that by explaining what workspace_id actually means semantically — it reads that workspace's linked company, only for owned personal workspaces, not an arbitrary partition. That is meaning the schema's "Optional workspace id" line does not carry.

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

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

States a specific verb and resource ("Read the company profile (Company Context)") and explains exactly what that object is: structured facts used as background for answers. It also cleanly splits the account-level vs workspace-linked read modes. It never names the sibling get_company, so an agent cannot tell from this text alone how this differs from that 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?

Explicit when-to-use ("when the user asks what ISMS Copilot knows about their company or a client"), explicit negative guidance ("Do not call it before a question unless the task needs the user's own data"), and an explicit sequencing rule relative to set_company_context. It even tells the agent not to mention empty results unprompted, which is a real usage decision.

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 substantial behavior beyond annotations: discloses the side effect that a stalled turn gets marked failed (consistent with destructiveHint=true and readOnlyHint=false), explains the returned flags (provider_fallback, overflow_active, answer_format_applied, beyond_run_status), usage semantics, and docgen_notice relay. No contradiction with the annotation 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?

Front-loads the core purpose and usage constraint, then layers polling guidance and flag handling; nearly every sentence carries actionable content. It is dense and long-winded in the flag-listing clause, but not 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?

Despite having no output schema, the description names the status values, the flags to inspect, and how to present results, covering what an agent needs to poll, interpret, and relay correctly. The side-effect disclosure closes the otherwise risky mutation 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; the description adds real value by saying where conversation_id/message_id come from ('from that call') and what beyond_run_id does ('pin that run'). It does not add format/syntax detail, which is fine given the schema already specifies UUIDs.

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 ('Fetch the reply for a turn') and ties it directly to the siblings that produce such turns (create_conversation, send_message) with the 'generating' status condition. An agent can distinguish this from send_message without opening either schema.

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

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

Explicit when-to-use ('turns that returned status generating'), when-not ('do not call it when the turn already came back complete'), and operational guidance (poll every 10–20 seconds for beyond turns until complete/error). Alternatives and exit conditions are named, 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?

Adds substantial context beyond the annotations (which only say readOnly=false, idempotent=true, destructive=false): the ownership precondition ('Both must be yours'), the plan-slot cost ('Links consume no plan slot'), the required scope ('company_context:write'), and the downstream effect (workspace turns inherit company facts, updates propagate). That is exactly the extra information annotations cannot 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 action, then usage trigger, then effect, then preconditions and permission. Every sentence carries distinct information, though the middle sentence about update propagation is slightly verbose for what it conveys.

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

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

For a 2-param mutation with no output schema, the description covers what is linked, prerequisites (ownership, scope), side effects (no plan slot, inherited facts), and lifecycle (create_company → link). Only the behavior on an already-linked pair is left to the idempotent annotation.

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

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

Schema coverage is 100%, and the schema already documents both UUIDs with their source listing tools. The description adds no parameter-level detail (no format, no edge cases for mismatched ownership), so it neither helps nor hurts beyond the schema baseline.

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

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

States a specific verb and both resources ('Link one of your workspaces to one of your companies') and clarifies the semantic meaning of the link as client context. It implicitly distinguishes itself from the unlink_workspace_company sibling, though it never names an alternative tool 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?

Gives concrete triggering conditions: 'Use it after create_company, or when the user says a workspace is for a given client.' That is clear when-to-use guidance, but there is no explicit when-not-to-use or direct pointer to the unlink/alternative sibling for disambiguation.

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 the description isn't carrying the safety burden. It still adds real value beyond them: it discloses that only metadata is returned and never secrets, and it states the required scope api_keys:read, which annotations do not cover. Minor gap: no mention of ordering or result size for large key sets.

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 the most consequential caveat (never secrets) before the usage routing. Nothing repeats the name or the 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?

For a no-parameter read tool with rich annotations, the description covers purpose, the security caveat, the required scope, and the downstream sibling. An agent has everything needed to select and call it correctly.

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

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

Zero parameters, so there is nothing for the description to disambiguate and the 100% schema coverage baseline applies. The description adds no parameter detail and needs none.

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

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

States a specific verb and resource (list this account's model API keys) and immediately scopes it as metadata-only, never secrets. That scope clause distinguishes it from any secret-returning operation and from the credit-balance 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 both a trigger (user asks which keys exist) and a chaining use (before revoke_api_key to find a key_id), plus an explicit exclusion pointing to get_api_credit_balance for balance questions. Lacks an explicit 'do not use create_api_key for this' statement but the routing is already 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds behavioral context the annotations cannot: what omitting 'assistant' actually does ('gives auto — the general specialist unless routing picks an expert') and what the general specialist covers. It does not mention output shape or ordering, but the read-only profile is fully declared elsewhere.

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 purpose and the usage rule are front-loaded, which is good, but the middle of the description enumerates all ten assistant names and ids — data the tool itself returns at call time. That enumeration duplicates the (unshown) return value and inflates the description well past what an agent needs before invoking it.

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 return values — and it does, listing every assistant and id along with the two grouping modes. Combined with the routing rule, an agent has everything needed to call this and act on the result.

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 of 4 applies. The description goes further by explaining the semantics of the 'assistant' argument on the sibling tools it feeds, mapping ids to concrete names, which is genuine added meaning rather than restatement.

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 opening sentence names the verb and resource precisely ('List built-in assistants') and immediately breaks the resource into its two enumerable categories (by_job, built_in) with their distinguishing attributes (jobs with skills vs frameworks). No sibling tool in the list returns assistants, so there is no ambiguity to resolve.

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 exactly when to call it ('before picking an id for assistant on create_conversation or send_message') and, unusually, when NOT to ('not needed when their description already shows the right id'). It then supplies a decision rule for job id vs framework id vs omitting the assistant entirely, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive/non-open-world, so the safety profile is covered. The description adds real behavioral context beyond that: the required permission scope (company_context:read) and the pagination contract (default 50, max 100, default offset 0). It stops short of describing ordering or empty-result 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?

Three tight sentences: identity/content first, then the routing rationale, then constraints. Every clause carries information an agent needs, and no sentence is redundant.

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 compensates by enumerating the returned fields (id, company_profile, created_at, updated_at), and it covers permissions and pagination. For a zero-required-parameter read tool, nothing essential is missing.

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

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

Schema coverage is 100% and both parameters are self-documented with the same defaults, so the description mostly repeats the schema. No additional semantics (e.g., ordering, what offset counts against) are supplied. 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+resource ("List your companies (client contexts)") and explains what each item contains (id, company_profile, created_at, updated_at). This clearly separates it from get_company, create_company, and the link/unlink siblings.

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

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

Explicitly states when to use it: to obtain a company_id (UUID) before calling get_company, update_company, delete_company, or link_company_to_workspace. The alternatives that consume the id are named, and the precondition is spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description focuses on what it adds: metadata-only output, no text content, and the instruction to stay silent on empty results. It stops short of saying whether results are ordered or bounded, which is the only remaining behavioral 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?

Six short sentences, front-loaded with purpose then scope then usage rules, with no repetition of structured data. The empty-result sentence is unusual but earns its place by preventing spurious user-facing output.

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 compensates by listing the returned metadata fields, and it fully covers invocation conditions for a one-optional-parameter read tool. Minor incompleteness around result ordering/volume is the only thing an agent might still wonder about.

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_id parameter is fully documented in the schema, including the list_workspaces reference. The description's 'optionally for one workspace' restates the schema without adding syntax or semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the user's uploaded documents') and immediately enumerates the metadata fields returned (id, file name, type, size, processing status, workspace, dates). It also distinguishes itself from adjacent operations by declaring it does not return document text and does not upload files.

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 trigger ('when the user asks which files ISMS Copilot holds'), an explicit exclusion ('do not call it before a question unless the task needs the user's own documents'), and even handling guidance for empty results. 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 a safe read (readOnly, idempotent, non-destructive, closed-world), so the description adds higher-order behavior instead: that the assistant already consumes memories internally, that calling it unnecessarily is discouraged, and that an empty list should not be surfaced unprompted. That is context the 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 purpose, then routing rules. Dense and mostly waste-free, though the final sentence about empty results could arguably fold into the preceding guidance without loss.

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?

Only one optional parameter, no output schema, and annotations cover safety. The description still covers scoping, when not to call, dedup use, and empty-result handling – everything needed to invoke 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 100% and already documents workspace_id as a UUID from list_workspaces. The description adds the decision rule – omit for personal memories, pass it to scope to a workspace – which tells the agent *when* to set it, not just what it is.

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 exact resource ('saved memories') and defines what a memory is ('short facts ISMS Copilot keeps as background'). Explicitly contrasts with get_company_context (company facts) and create_memory (dedup check), so an agent can place it among siblings without opening schemas.

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

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

Gives explicit triggers ('user asks what ISMS Copilot remembers', 'before create_memory to avoid a duplicate'), explicit exclusions (company facts → get_company_context; don't call preemptively since the system already uses memories), and even guidance on silence for empty results.

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 'only reads' sentence largely restates them. The description still adds value by disclosing the ownership filter (only workspaces the user owns) and the UUID form of the identifier, which annotations do not convey. Pagination, ordering and what fields come back are unstated.

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

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

Three short sentences, zero filler. The core purpose is front-loaded, followed by the practical routing advice and the scope guard. Nothing repeats the tool name or wastes tokens.

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-argument, read-only list tool whose safety profile is fully covered by annotations, the description is nearly complete: it explains why to call it and what identifier it yields. It could mention what else a workspace record contains (e.g., name) to set expectations around the return shape, which has no output schema.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and no description burden is created. Baseline 4 applies; the note that workspace_id is a UUID is a helpful return-value hint rather than a 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?

States a specific verb and resource with scope: 'List the workspaces the user owns.' The closing clause ('does not create, rename or share') explicitly separates it from create_workspace, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives an explicit trigger — call this to obtain the workspace_id needed before create_conversation, list_memories, list_documents or get_company_context — and an explicit exclusion (no create/rename/share). The when and when-not are both stated, naming the concrete downstream 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?

Goes beyond the destructiveHint=true annotation by spelling out the concrete effect ("calls made with it stop working") and the irreversibility ("cannot be undone"), and adds an authorization requirement ("Requires api_keys:write") that annotations do not carry. This is exactly the extra context a mutation tool needs.

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

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

Two tight sentences front-loading the action and consequence before the usage constraint. No filler, and the most decision-relevant facts (irreversibility, permission) come early.

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?

Single required parameter, full schema coverage, rich annotations, no output schema to explain. Effects, authorization, and input sourcing are all covered; nothing an agent needs in order 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% and the property description already says "a UUID from list_api_keys," so the description's provenance note largely restates structured data. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb (revoke) and resource (model API key) scoped by id, which cleanly separates it from create_api_key and list_api_keys in the sibling set. The consequence clause reinforces exactly what the operation does.

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

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

Explicit invocation condition ("only when the user asks to revoke a key") plus the prerequisite workflow for obtaining the argument ("get the key_id from list_api_keys"). That is a when-to-use, a when-not-to-use implication, and a pointer to the sibling that supplies input.

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 mark it as non-read-only and open-world; the description adds far more: the return shape (conversation_id, message_id, status 'complete' vs 'generating' → poll get_reply), rate-limit errors carrying reset_at, the fallback_available/overflow_consent path with the explicit-user-consent precondition and the no-duplicate-save guarantee, docgen_notice relaying, and a data-sensitivity prohibition. That is substantive behavioral context beyond the annotation 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?

Front-loaded correctly: purpose and the two negative routing rules come first, then parameter nuance, then return/error behavior, then safety. Every block is functional, though the ten-bullet assistant catalogue is long and largely recoverable via list_assistants, which makes it slightly heavier than necessary.

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

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

There is no output schema, so the description carries the burden of describing returns — it does, including the 'generating' state and the polling handoff. Combined with error-path guidance, the consent rule, and the privacy constraint, an agent has everything needed to call this correctly, including what to tell the user 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 the baseline is 3, and the description earns above that by adding selection logic the schema lacks (the assistant routing rule and the note that mode/answer_format mirror create_conversation) plus the consent gate on overflow_consent. It stops short of 5 because much of the assistant detail restates ids the schema already points at via list_assistants.

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 and resource ('Continue a conversation with the ISMS Copilot GRC specialist on the same deliverable') and even enumerates the continuation shapes: refine a policy, extend a gap analysis, ask the next question. It explicitly contrasts itself with create_conversation (new deliverable) and get_reply (in-flight turn), so an agent can place it among siblings without reading schemas.

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

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

Gives both positive triggers and explicit exclusions with the correct alternative named for each: don't start a new deliverable (use create_conversation), don't send while the previous turn is generating (wait for get_reply, 'a send then is rejected'). It also supplies a decision rule for the optional assistant parameter ('a task to do takes the job id... a question about one framework takes that framework's id; else omit'), which is exactly the guidance 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 only declare destructiveHint/idempotent/readOnly; the description goes far beyond, spelling out that omitted fields are cleared, blank values are omitted, an empty object clears or unlinks, a linked company full-replace propagates to every linked workspace, an unlinked workspace creates a new company atomically with a plan limit enforced, and that company_context:write is required. It also closes a likely false assumption by noting it does not switch the profile on or off for answers.

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 destruction warning is correctly front-loaded, and almost every clause carries decision-relevant information. It loses a point for a single dense block and one garbled clause ("turns in it then use no company profile") that forces the agent to re-read the unlink 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?

For a destructive, 10-parameter, output-schema-less mutation tool, this covers the destruction model, the prerequisite read, permission scope, alternative tools, and the full branching of workspace targeting. An agent has everything needed to call it correctly or correctly decline.

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 field-level meaning is already documented; the description adds genuinely new semantics only for workspace_id — account-level default when absent, workspace client context when present, and the divergent linked vs unlinked vs empty-object outcomes. The remaining nine fields get no added description-level meaning, which is acceptable given the 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?

Opens with a specific verb+resource combination ("Full-replace the company profile (Company Context)") that immediately distinguishes it from update_company and from get_company_context. The parenthetical naming of the object and the explicit full-replace framing let an agent tell it apart from 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?

Explicitly states when to use it ("only when the user asks to set or update their company or client profile"), when not to ("do not use it for one-off facts (create_memory)"), and names a prerequisite read ("read it first with get_company_context"). It routes the agent to two alternatives by name with the conditions that select them.

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 key side-effect boundary: the company item is kept and other linked workspaces keep their link. It also states the required permission 'company_context:write,' which is actionable authorization 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 description is short and front-loads purpose, trigger, and side effects. The phrase 'turns in the workspace then use no company profile' is slightly awkward, which keeps it from being perfectly concise.

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 mutation with annotations and no output schema, the description covers what it does, when to use it, what is preserved, the alternative tool, and required permission. Nothing essential for selection or invocation is missing.

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

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

Schema description coverage is 100%, and the single workspace_id parameter is already documented as a UUID from list_workspaces. The description does not add parameter-specific syntax or constraints, so the baseline of 3 is appropriate.

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

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

The description states a specific verb, 'unlink,' and resource, 'workspace's company,' and distinguishes it from deleting the company by noting that the company item is kept. The client-context wording and the sibling alternative make it easy to separate from link_company_to_workspace and delete_company.

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 an explicit trigger: 'Use it when the user says a workspace is no longer for that client.' It also names the alternative for a different intent: 'to remove the company itself, use delete_company.'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new context beyond that — blank values omitted, omitted fields cleared, all linked workspaces updated at once, and the required company_context:write scope. The only gap is that it doesn't say what the response looks like or how partial failures across linked workspaces are 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?

Four sentences, each carrying distinct load: operation semantics, when to use, blast radius, edge case, and auth requirement. Replace semantics and the read-first warning are front-loaded where they matter most.

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 destructive mutation with no output schema, the description covers the semantics, the permission requirement, the cross-workspace impact, and the empty-payload behavior. Nothing an agent needs in order to call it safely 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 per-field meanings are already documented and baseline would be 3. The description earns above baseline by explaining replace-vs-merge behavior for the ten optional fields — that omitted fields are cleared and an empty object wipes facts — which the schema cannot express.

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 ('Full-replace a company's profile by id') and pins the semantics with 'PUT semantics', which separates it cleanly from create_company and get_company. An agent knows exactly what operation this is without opening the schema.

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

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

Gives an explicit trigger ('Use it when the user changes a client's facts') and an explicit prerequisite route ('read it first with get_company'), naming the sibling tool to call first. It also covers the degenerate case (empty object) so the agent knows the outcome of that 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value beyond them by stating the old text is overwritten and by pointing to list_memories as the id source. It stops short of saying whether the overwrite is reversible or how errors surface, 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?

A single tight sentence-cluster: the operation and its constraint come first, then the when-to-use, then the id source, then the excluded sibling. No filler and nothing buried.

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 no output schema, the description covers what changes, the size limit, the id prerequisite, and the nearest alternative. Only minor operational details (reversibility, failure behavior) are absent, which is acceptable at 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%, so both parameters (content, memory_id) are already documented with type, max length, and UUID origin. The description restates those same facts rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Replace the text of an existing memory by id') plus a concrete constraint (max 500 characters) and the overwrite effect. It is clearly distinguished from the sibling create_memory, which it names 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?

Gives an explicit trigger ('when the user asks to correct or change something ISMS Copilot remembers'), a prerequisite step ('get the id from list_memories'), and a stated exclusion ('Do not use it to add a new memory (create_memory)'). 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.