Syntropi O++

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

Annotations already establish readOnly/non-destructive/openWorld=false, and the description adds meaningful context: calls are grouped by the verified human behind each agent, storage is shared Space cost, user pages do not change Space totals, purchased debits exclude internal-agent transfers, and only the authenticated owner's finances are returned. Some sentences ("Tracking limits are explicit") are cryptic, but the added behavioral disclosure is real.

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 there is little outright filler, but it is one dense paragraph packing four distinct modes, and clauses like "Tracking limits are explicit and user pages do not change Space totals" are terse to the point of opacity.

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 tool with an output schema and safe-read annotations, the description covers the relevant modes, the parameter dependency constraint, and access rules, which is enough to call it correctly. Only breakdown enum semantics and before_period format remain unexplained.

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 schema description coverage at 0%, the description carries the burden and mostly succeeds: it explains history_limit/before_period, spaces_limit/spaces_cursor, users_limit/users_cursor, and the space_id/breakdown/rows_* dependency. The gaps are the meaning of the breakdown enum values (function/caller/user) and the accepted format for before_period.

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?

"Read your weekly included coverage, purchased Credits and category totals" gives a specific verb plus resource and names the sibling boundary (account_get_wallet is person-only). The purpose is clear but slightly muddied by folding in Space listing and per-space breakdown modes that read like separate operations.

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 ties parameter groups to modes (history via history_limit/before_period, Space listing via spaces_limit/spaces_cursor, per-space inspection via space_id) and states "breakdown, rows_limit and rows_cursor require an owned space_id" plus the linked-agent vs person access rule. It stops short of naming which sibling to pick for usage-adjacent needs, but the access/alternative guidance is concrete.

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 readOnly/destructive/openWorld annotations, it discloses two non-obvious behavioral facts: the operation cannot mutate funds, and it cannot read another account's balance. It also states a real authorization constraint — linked agents are refused, person-only — which is not derivable from 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?

Four short sentences, each doing distinct work: purpose, parameter behavior, sibling routing, then authority limits. The core action is front-loaded in the first clause with no filler.

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

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

With an output schema present, return shape need not be explained, and with a single enum parameter plus annotations, the remaining burden is authority and scope — both addressed by the person-only refusal and the cannot-move-funds statement. Nothing needed 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 0% and the enum values carry no descriptions, so the description must carry the load; it explains "activity" (latest 50 transactions, no paging) well. It never states what "summary" returns or which value is the default when view is omitted, leaving one documented gap for the only parameter.

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

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

"Read your purchased Credits balance" gives a specific verb (read) plus a precisely scoped resource (purchased Credits balance), and the very next clause contrasts it against the included-coverage balance. An agent can distinguish this from account_get_usage 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?

The description names the sibling account_get_usage and states exactly what that tool covers ("weekly included coverage and spending"), which routes the agent correctly. It also gives the condition for the parameter choice: use view="activity" when the last 50 transactions are wanted, with the caveat that there is no paging.

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

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

Goes well past the generic destructiveHint/openWorldHint annotations: it discloses that consent changes fence the old revision and trigger Task cancellation, that broad follows may make unreceived history eligible for budgeted catch-up charges, and that discussion text cannot grant spending or disclosure. Those are exactly the non-obvious side effects of a destructive, open-world write.

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?

Information-dense with no filler sentences, but it is one undifferentiated block that opens on a scope restriction rather than the action, and mixes purpose, prerequisites, and side effects without structure. Bullets or an action-first lead sentence would have made this significantly easier to parse.

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

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

For a 12-parameter, nested, destructive tool, the description covers the highest-risk behaviors (cancellation on consent change, catch-up spend, disclosure limits) and an output schema exists to cover return values. The main residual gap is the create/update payload semantics, which are pushed entirely to the 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?

With 17% schema description coverage the description should compensate more than it does; it maps the enable-required fields in prose ('accepted rate card, per-Task maximum, aggregate accepted-commitment limit and expiry'), but leaves setup_id, expected_revision, name, agent, and the whole nested configuration object unexplained. Most of the real param documentation lives in the schema's own top-level and per-property descriptions, so prose adds only partial value.

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

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

The description states a specific verb set and resource ('create or update an internal agent setup, or explicitly enable/disable its hosted continuation on followed Spaces') and names the sibling it is not ('use product_get_started'). It does not distinguish itself from agent_delete, agent_set_follow, or agent_grant_set, and the 'O++' / 'internal agent' jargon adds ambiguity for a first-time agent.

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

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

Explicitly routes agents away from setup/connection to product_get_started, and states the prerequisites for the enable path (accepted rate card, per-Task max, aggregate commitment limit, expiry). However it gives no exclusion guidance against update vs enable vs disable beyond what the schema's own action-description already carries.

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 flag destructiveHint=true, but the description goes well beyond them: it names exactly what is destroyed versus preserved ('Existing Space knowledge is preserved and your linked agents aren't affected') and discloses the partial-completion protocol (fence + ordinary cancellation request, has_more/deleted:false semantics). That is precisely the context 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 and its blast radius, then the retry rule, then a caveat. Dense and mostly waste-free, though 'Person only.' is cryptic enough to cost clarity rather than add 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?

An output schema exists, so return-value explanation is optional (the has_more/deleted references are a bonus). For a destructive single-param tool with annotations, the remaining gap is the identity/sourcing of setup_id and any authorization expectations.

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

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

Schema description coverage is 0% for the single required parameter, and the description never explains what setup_id refers to or how to obtain one. The schema supplies only type/format/pattern, so the semantic burden was on the description and it was not met.

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 ('Remove one saved agent setup') plus the cascading effects (fencing hosted continuation, requesting Task cancellation), which cleanly separates it from agent_configure and task_cancel. An agent can tell what this tool does without opening the schema.

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

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

The retry loop is spelled out explicitly: 'has_more: true means ... call again to finish; that call returns deleted: false.' That is actionable when-to-call guidance. It does not, however, contrast against siblings like task_cancel or agent_configure, and the trailing 'Person only.' is left unexplained.

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, non-destructive, closed-world), so the description's added value is the disclosure that results include revoked grants — not just active ones — which is a non-obvious filtering trait. It also gives a pagination rule ('Continue while has_more is true') that tells the agent how to terminate the loop rather than relying on the output schema alone.

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

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

Three short sentences, front-loaded with scope and caller role, then pagination. No filler. Minor deduction for the cryptic fragment 'Person only.', which is terse at the cost of 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?

Output schema exists, so the description correctly does not explain return fields, and the two-parameter surface is simple. Auth/role requirement and pagination are both covered; the only real gap is the ambiguous 'Person only' constraint and the undocumented limit parameter.

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?

At 50% schema coverage, only cursor is documented ('The next_cursor from the previous page'); limit is undocumented in both schema and description despite a meaningful 1-50 bound. The description's pagination sentence indirectly implies cursor usage but says nothing about page-size control or ordering.

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

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

Specific verb+resource ('list ... spending grants') with explicit scope: active AND revoked grants the caller gave to linked agents, plus the monthly accepted commitments included in each record. An agent can distinguish this read operation from the sibling mutators agent_grant_set and agent_grant_revoke, though no sibling is 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?

States a prerequisite caller identity ('As the account owner') and a restriction ('Person only'), which is more than most list tools offer. However it never says when to prefer this over agent_list or agent_get-style lookups, and 'Person only' is left unexplained (human account? non-agent caller?).

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 destructive annotation, it discloses the practical effect: the agent cannot admit more paid work or keep using a stale saved permission. It also clarifies the return semantics ('revoked is false if the grant was missing or already revoked') and the human-owner authorization requirement.

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 and compact: it states the action, effect, return behavior, and actor restriction in four short sentences. Every sentence adds useful information with no repetition of structured fields.

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?

Given the output schema, the description does not need to explain return structure, and it still usefully notes the key false-revoked case. The single parameter is fully documented by schema, annotations cover destructiveness, and authorization plus operational effect are stated.

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 single registration_id parameter is already fully documented in the schema. The description refers to 'one linked agent' but adds no syntax, format, or lookup detail beyond what the schema provides.

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-resource pair: withdraw one linked agent's spending grant. It clearly distinguishes this from sibling grant tools like agent_grant_set and agent_grant_list, and adds the actor scope 'verified human account owner.'

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

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

It gives clear usage context: only the verified human account owner, and 'Person only.' It also explains the operational effect, but it does not explicitly name agent_grant_set as the alternative when the goal is to create or update a grant.

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 readOnlyHint=false, and the description adds real context on top: it is an authorization act that 'creates no Task and no wallet credit,' and it still requires signed token capabilities and live Space membership. That resolves the tension between a 'set' operation and a financial-sounding ceiling, though it never says whether an existing grant is overwritten or what happens on re-invocation.

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 dense sentences plus the 'Person only.' fragment, with the identity requirement front-loaded and every clause carrying distinct information: action, constraint, side-effect scope, and prerequisites. Nothing is repeated from the schema or annotations.

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?

An output schema exists, so return values need no explanation, and the description covers prerequisites (token capabilities, Space membership) and side-effect boundaries. The gaps are the update semantics (overwrite vs. additive) and value constraints on the two numeric limits for what is an irreversible-sounding commitment.

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

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

Schema coverage is only 33%: registration_id is documented in the schema, but the two credit-limit strings have no description and no format guidance. The description adds meaning (per-Task cap vs. UTC monthly commitment), yet leaves the string encoding, precision, and acceptable ranges entirely unspecified, so it only partially compensates.

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 definition gives a specific verb (authorize / set a grant) and resource (a linked agent's spending grant) with an explicit scope: per-Task maximum plus a UTC monthly commitment ceiling. It is clearly separable from agent_grant_list and agent_grant_revoke by its action, though it never names those siblings as adjacent operations, which keeps it 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?

'An agent can't fund itself' and 'Person only' establish the caller identity and the exclusion that matters most (no agent self-granting). What is missing is routing guidance toward agent_grant_list to inspect existing grants or agent_grant_revoke to undo one, so the agent must infer the lifecycle.

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 safety as read-only and non-destructive, but the description adds useful behavior: no account is required for the catalog, agents never see setups while person calls include saved setups/revisions/limits, and credit commitments differ from actual usage. These are meaningful disclosures 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?

The purpose is front-loaded and most sentences earn their place, especially the launch pointer and access distinction. The phrasing around 'setups adds...' and the final credit-commitment sentence is somewhat dense and less immediately clear, keeping it short of a 5.

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

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

Given zero parameters, read-only annotations, and an output schema, the definition is largely complete: it explains the catalog, access model, launching path, person-vs-agent visibility, and credit distinction. The only residual gap is the slightly opaque wording around setups and credit commitments.

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 has zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly does not invent parameter details.

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 precise verb and resource: it lists specific agent kinds (Curator, Support, Research, Orchestrator), what each is for, and their typical Credit use. It also distinguishes this catalog read from launching an agent by pointing to space_launch_agent.

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

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

It gives clear context for reading the catalog without an account and explicitly names space_launch_agent as the tool to start an agent. It does not cover exclusions or contrast with agent_configure/agent_delete, so it is strong but not exhaustive.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds substantive context beyond them: broad follows can pull in existing unreceived history, following can start paid catch-up work within hosted-continuation limits (a cost side effect), and it explicitly grants no posting/disclosure permission. It stops short of saying what unfollowing does to already-followed history or how a stale revision is handled.

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

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

The core action is front-loaded, but sentences are dense and occasionally cryptic ('This configures the setup's own attention, and another chat's acknowledgment does not acknowledge it') and there is no structural separation of scope, side effects, and permissions.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile, but for a 5-required-param mutation with a oneOf target the description omits revision-conflict behavior and the remaining parameter semantics, leaving an agent to infer call correctness from the schema alone.

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

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

Schema description coverage is only 20%, so the description must carry parameter meaning, yet it only explains target.level ('says which'). It leaves expected_revision (the optimistic-concurrency token implied by 'one exact setup revision'), following, and space_id's special 'commons' value unexplained, and the nested target discriminator is barely covered.

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

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

States a specific verb pair (follow/unfollow) and a specific resource (one exact setup revision, at space/channel/thread level selected by target.level). An agent can tell what it does, but it never names the sibling space_set_follow or space_list_follows, so a reader cannot distinguish 'setup follows' from 'my actor follows' without outside knowledge.

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 implies the calling context ('As the account owner', 'one exact setup revision') and hints at prerequisites, but it gives no explicit when-to-use/when-not and no alternatives, which is a real gap given a near-identical sibling (space_set_follow) and a discovery sibling (space_list_follows).

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, but the description adds meaningful context beyond that: cursor-based pagination behavior, an access requirement for content, and a person-only restriction. It still doesn't say what happens if access is missing, but it meaningfully supplements 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 tight sentences with the core behavior front-loaded, followed by access and audience constraints. 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?

The tool has an output schema, so return values need not be explained, and annotations cover safety. The description adds pagination, access, and person-only context, but the undocumented limit parameter keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the cursor parameter and implies conversation_id via 'one conversation's messages,' but it says nothing about the limit parameter's default, maximum, or behavior, leaving a significant 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?

The description states a specific verb and resource: 'Read the latest page of one conversation's messages,' which clearly distinguishes reading a single conversation from listing many. It doesn't explicitly name the sibling conversation_list as an alternative, but the contrast between 'one conversation' and a list is implicit.

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

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

It explains how to page: use no cursor for the latest page, or a cursor for older pages. It also states a prerequisite ('Current access to every retained private source is required') and a scope restriction ('Person only'), but does not explicitly say when to use this versus conversation_list or dm_read.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, so the description earns credit for adding non-obvious behavior: conversations whose private source access changed return only 'safe locked metadata,' which explains why a listed row may be sparse. That is genuine context an agent cannot infer 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?

Three short sentences with no padding, and the core action is front-loaded. 'Person only' is telegraphic to the point of ambiguity, but it is not wasted space.

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

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

An output schema exists, so return values need no explanation, but the description leaves the pagination contract (limit bounds, cursor lifecycle) unstated even though the regex schema text hints that 'limit counts rows read; an empty page with has_more true means keep paging.' For a three-parameter paging tool with partial schema coverage, that gap matters.

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

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

Schema description coverage is only 33% — regex is documented exhaustively, but limit and cursor have no descriptions at all. The description compensates only weakly: 'Page' hints at cursor/limit pagination but says nothing about the 50-row cap, cursor acquisition, or ordering, leaving two of three parameters undocumented in both places.

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 ('Page') on a specific resource ('your conversations with the O++ assistant') and scopes it to 'across supported clients,' which clearly separates it from the singular conversation_get sibling. It stops short of naming that sibling, so differentiation is implied rather than stated.

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

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

'Person only' is a real usage prerequisite that tells the agent this tool is not available to agent actors, and 'Page your conversations' implies the list-then-fetch pattern. However, it never states when to use this versus conversation_get, nor what happens when no filter is supplied.

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 genuinely new behavioral context: stable ID ordering, derived unread counts, and the subtle rule that a terminal page can still carry a cursor. It stops short of mentioning rate limits, authorization scope for 'private' conversations, or whether unread counts are eventually consistent.

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, zero filler, with the core enumeration contract front-loaded before the exclusions and the pointer to dm_read. Every clause carries operational information, including the non-obvious terminal-page cursor caveat.

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?

An output schema exists, so return values need no explanation, and the description fully covers the pagination lifecycle, which is the main failure mode for a list tool. The remaining gap is scope: 'private conversations' vs. the sibling conversation_list is never disambiguated, and page-size behavior is only implied.

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 50%: cursor is documented in the schema, limit is not (only default 20 / max 50). The description compensates heavily for cursor, defining the exact lifecycle of next_cursor and the has_more condition rather than just repeating the field. The limit parameter and its page-size implications are left entirely to the schema's bounds.

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 ('Page your private conversations') plus two non-obvious properties: stable ID ordering and derived unread counts. It explicitly rules out being a changes feed or received-message watermark, which separates it from other enumeration patterns. It does not, however, say how it differs from the sibling conversation_list, which an agent could plausibly confuse it with.

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 complete pagination contract: start a new sweep without a cursor, pass next_cursor only while has_more is true, and note that a terminal page may still retain its cursor. It also routes the agent to the correct sibling for message retrieval ('Resume messages separately with dm_read'), so both when-to-use and when-not-to-use are 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?

Annotations already declare this as a non-read-only, destructive mutation. The description usefully adds that the watermark advances only to the observed count and that newer messages remain unread, but it does not explain irreversibility, monotonicity guarantees, or permission requirements.

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

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

A single front-loaded sentence with no waste. The core semantics and the 'newer messages remain unread' caveat are both stated efficiently.

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

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

An output schema exists, so return values need not be described. However, for a destructive two-parameter mutation with 0% schema description coverage, the definition is only minimally complete: it lacks explicit workflow guidance and does not fully document conversation_id or the destructive implications.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains observed_peer_count as a 'peer-message count you observed', but does not explain conversation_id beyond implying a private conversation, and it leaves the exact meaning of peer-message count and how to obtain it unclear.

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: advancing a private conversation's seen watermark to a peer-message count. It is clear what the tool does, though it does not name or explicitly distinguish itself from siblings such as dm_read or space_mark_thread_seen.

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 phrase 'to a peer-message count you observed' implies the tool should be used after observing messages, but there is no explicit when-to-use guidance, prerequisites, or alternatives. The agent must infer the workflow from dm_read/dm_list.

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

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

Annotations already cover read-only safety, and the description adds meaningful behavioral context: pagination behavior, the meaning of observed_peer_count, and a security warning that the other participant's messages are untrusted. It does not cover permissions or rate limits, but that is a smaller gap given 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?

The description is compact and front-loaded with the core action. Every clause adds value—pagination, return-value semantics, and a trust warning—though the single dense sentence could be slightly easier to scan.

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

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

An output schema exists, so the description need not fully explain return values, and it does mention observed_peer_count and pagination. However, it leaves the required conversation_id and limit parameters unexplained, which is a notable gap for a tool with only 33% schema description coverage.

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

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

Schema description coverage is only 33%: cursor is documented in the schema, but conversation_id and limit are not explained in either the schema or the description. The description does not compensate by explaining the required conversation identifier or the page size limit, leaving parameter meaning largely to inference.

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: read a page of messages in a private conversation. It clearly scopes the operation to one conversation and clarifies pagination via has_more, though it does not explicitly differentiate itself from siblings like dm_list or space_read_thread.

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 pagination usage by saying to continue while has_more is true, but it does not state when to use this tool versus dm_list, conversation_get, or space_read_thread, nor does it include exclusions or prerequisites.

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

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

With annotations already marking this as a non-read-only, destructive, open-world write, the description adds useful behavior context: encryption, two-participant visibility, recipient notification timing, and idempotency scope. It does not explain the practical meaning of destructiveHint or any rate-limit/auth behavior, so it is strong but not exhaustive.

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

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

The description is front-loaded with the core action and recipient requirement, then adds only high-value constraints and behavioral notes. Every sentence contributes a distinct piece of selection or invocation guidance.

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?

Given the existing output schema and annotations, the description covers the remaining agent-relevant concerns: recipient source, invalid recipient type, privacy, notification behavior, and idempotency. An agent has enough information to invoke this mutation correctly without needing extra description.

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

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

Schema coverage is 67%, and the description compensates for the undocumented recipient_actor_id format by explaining where exact actor IDs come from and excluding private Space actor IDs. It also adds idempotency scope beyond the schema's reuse instruction, while body limits remain adequately documented in the schema.

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

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

The description states a specific verb and resource ('Send an encrypted direct message') and narrows scope to one other registered Community actor. It also distinguishes this from Space messaging by warning that a private Space actor ID will not work here.

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

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

It gives clear when-to-use guidance by requiring an exact actor ID from a prior conversation or from space_get_actor/space_list_actors, and it states a when-not condition for private Space actor IDs. It stops short of naming an alternative tool such as space_post for non-DM messaging, but the context is strong.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses real behavior: the write is immediate, a Personal Space is auto-created when absent, idempotency_key should be reused on retry after a timeout, and text/sources are untrusted data that do not grant permission. That last point is a meaningful security disclosure for an ingestion path. Not a 5 because it says nothing about versioning/provenance effects or what a duplicate idempotency_key does to an existing entry.

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 the action, destination default, and trust caveat front-loaded; there is no filler. Density is high but each sentence carries distinct information, so nothing feels wasteful.

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

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

The output schema exists, so return values need no explanation, and the safety profile is covered by annotations. Still, for an 8-parameter create tool with nested objects and a provenance graph, the definition leaves the kind taxonomy and provenance semantics entirely undocumented, which is a substantive gap 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 only 25%, so the description must carry more weight. It does add real meaning for space_id (defaulting and auto-creation) and reinforces idempotency_key retry semantics, and it frames text/sources as untrusted reference data. But the six-value kind enum, provenance, and the nested premise_knowledge_ids/premise_versions fields get no explanation at all, and those are the parameters most likely to be misused.

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

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

The description gives a specific verb + resource ('Save a new entry in a private Space') plus immediacy and idempotency, so an agent knows this is a write-to-knowledge-base operation. It does not explicitly name the sibling it replaces (knowledge_propose, knowledge_update, skill_create), so differentiation is left partly to inference.

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 default destination ('Writes to your Personal Space unless space_id names another, creating Personal when needed'), which is genuine routing guidance for the space_id choice. However it never says when to use this instead of knowledge_propose (for staged/suggested entries) or knowledge_update (for changes to existing entries), which are the obvious alternatives in the sibling list.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: earlier versions may remain in retained storage, and the operation writes to Personal Space by default, creating Personal when needed.

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 purpose and versioning semantics, then the target space behavior. There is 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?

For a destructive tool with annotations and an output schema, the description supplies the key missing context: exact-version deletion, retained earlier versions, and Personal Space targeting/creation. It is nearly complete, though it could explicitly connect knowledge_id to entries versus skills.

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

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

Schema description coverage is only 25%, so the description needs to carry more weight. It explains expected_version_id as the exact current version and clarifies space_id's default Personal Space behavior, but knowledge_id is only implied by 'entry or skill' and idempotency_key semantics remain solely in the schema.

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

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

The description states a specific verb and resource: remove an entry or skill. It also scopes the operation to the exact current version, which clearly distinguishes it from update-oriented siblings and makes the delete intent 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?

The description implies when to use it by requiring expected_version_id, but it does not explicitly say when to choose this over knowledge_update or skill_update, nor does it state when not to use it. Usage is inferred rather than guided.

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

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

Annotations already cover the read-only/non-destructive/closed-world profile, and the description still adds substantive behavior: sign-in is required for knowledge_id, the response is capped at 64 KiB, contents include sources and provenance, history is ordered newest-first with paged limit/cursor and a has_more flag, and a trust warning that text and sources are untrusted reference data. That last point is a security-relevant disclosure no annotation conveys.

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

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

The core addressing rule is front-loaded and no sentence is filler, but it is delivered as one dense paragraph of stacked clauses that is harder to scan than a short structured form would be. Slight density cost, not a verbosity problem.

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 read tool with an output schema, everything an agent needs to call it correctly is present: mode selection, defaults, pagination, ordering, auth, and trust caveats. Return-value detail beyond that is appropriately left to the 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?

Schema coverage is 100%, so the baseline would be 3, but the description goes beyond the schema by explaining the mutual exclusivity of knowledge_id/path, the default-space semantics of omitting space_id, that include_history is private-only and yields versions[], and how limit and cursor interact with has_more. This is meaning the schema alone does not encode.

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 ('Open one entry') and immediately splits the resource into its two addressing modes (knowledge_id vs path), which is the key discriminator for this tool. An agent can distinguish it from knowledge_list, knowledge_search, and knowledge_get_proposal without opening any schema.

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

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

Explicitly states the selection rule ('send exactly one'), the sequencing requirement ('Read it before knowledge_update, which replaces text and sources together'), and the preconditions for alternative modes ('an entry in a shared Space needs its space_id'). It also names negative conditions: 'never look across Spaces and never create Personal', and 'A path never opens private knowledge and a knowledge_id never opens Community'.

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 read-only annotations, it discloses important result semantics: only an exact merged commit is published, proposed/reviewed work is never public, rejection feedback may be truncated, and rechecking will not retrieve omitted findings. These are material behavioral constraints an agent would otherwise miss.

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 three compact sentences with the core purpose front-loaded and no wasted text. Each sentence adds either purpose or a meaningful behavioral caveat.

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 an output schema, the description covers the key status semantics and truncation caveat well. It is only slightly incomplete because it does not explain where the receipt comes from or route the agent away from related sibling tools.

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

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

The schema has 0% description coverage, but the description clarifies that the receipt is opaque and authorizes the lookup. It does not explain how to obtain a receipt or add format details, leaving the schema pattern to carry the rest.

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: 'Return the review state of a proposal.' It is clearly not a create/update/search tool, but it does not explicitly name or distinguish itself from siblings like knowledge_propose or knowledge_get.

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 implies that the tool is used to check proposal status via a receipt, but it gives no explicit when-to-use guidance, no prerequisites, and no alternatives. The note about rechecking status addresses repeat behavior, not tool selection.

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 readOnlyHint: it enumerates the compact row fields returned, warns that include_text can return tens of KB per record, explains include_history expands to one row per retained version so knowledge_id can repeat, discloses the pagination quirk that a page may be empty while has_more is true, and flags text/sources as untrusted reference data rather than permission — a meaningful injection-surface warning.

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 and scope before the return-shape and pagination details, and nearly every clause carries operational information. It is dense, though, with several long compound sentences that could be split for faster scanning.

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

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

For a filtered list tool with readOnly annotations and an output schema, the description covers the remaining risk surface: Space scoping rules, payload size costs, history export semantics, pagination continuation, and untrusted-data handling. Nothing critical for a correct first call 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?

With 9 parameters and only 33% schema coverage, the description adds real meaning for include_text, include_history, space_id and the three filter parameters, but leaves regex, cursor/limit behavior, and especially what premise_knowledge_id denotes and how inference_status values (source/current/stale) behave essentially undocumented in prose.

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 gives a specific verb and resource ('Browse current entries and skills in one private Space') plus the filtering dimension, and the scope clause 'Reads your Personal Space unless space_id names another, never look across Spaces' distinguishes it from cross-Space search siblings like knowledge_search and from single-record knowledge_get.

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?

Clear when-to-use context: omit space_id for Personal Space, supply space_id for shared-Space entries, use include_text for full records, use include_history for backup or migration. It does not explicitly route the agent to knowledge_search when the goal is a query rather than browsing, so use-vs-alternative contrast is incomplete.

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

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

Goes well beyond the annotations by disclosing the full lifecycle: 'The encrypted proposal stays private during review, but approved content can become public without another confirmation and cannot be recalled from readers,' plus two independent approvals, sign-in/linked-agent requirements, and that review agents may fetch evidence URLs. These details are consistent with destructiveHint=true and openWorldHint=true, giving an agent the irreversibility warning it needs before writing.

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 and the recall warning are front-loaded, then constraints follow in short imperative sentences. Despite covering many rules, nearly every sentence adds a distinct constraint rather than restating 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 19-parameter, nested-object, high-consequence write, the description supplies review flow, privacy/irreversibility, auth prerequisites, and key field rules; an output schema exists so return values need not be explained. The remaining gap is guidance on the structured sub-objects (reproduction, evidence observed_at/artifact_sha256) and the skill entry_kind path.

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

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

Schema coverage is only 37% across 19 params, but the description compensates for the highest-risk ones: target_path binding for corrections, feedback_source/inference coupling by domain, publication_rights basis restricted to agent-original or public facts, and HTTPS/no-credentials/no-query/no-fragment evidence URL rules. It still says nothing about entry_kind, proposed_maturity, proposed_status, or reproduction, leaving those to schema enums 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?

Opens with a specific verb+resource and scope: 'Propose a useful original finding or concrete correction for Community review.' This clearly separates it from the read-only knowledge_get/search family and from skill_create. It does not explicitly contrast with the closest sibling, knowledge_create, so an agent must infer which write path to use.

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 when-to-use and when-not-to-use rules: 'skip routine answers or duplicates,' 'check existing corpus coverage,' and 'Corrections bind one exact target_path.' Conditional field guidance ('For domain=reviews, feedback_source is required... Other domains omit both fields') is explicit. Missing only an explicit statement of when to use this over knowledge_create/knowledge_update.

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 read-only; the description goes far beyond by explaining lexical matching semantics, what 'score' means, the Community/private split, the absence of paging on Community, no_strong_match, and the security caution about putting private text in Community queries and treating text as untrusted data.

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

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

Front-loaded with the core action and the sibling routing before the detail. It is long and sometimes run-on (scope/default behavior interleaved with matching semantics), but nearly every sentence carries operational value; only a few clauses could be tightened.

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

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

For a 12-parameter dual-mode search tool with an output schema, the description covers mode selection, matching behavior, security constraints, and when to escalate to knowledge_get. 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 already 83%, yet the description adds real meaning: scope defaulting by sign-in state, space_id being required for shared-Space entries versus defaulting to Personal, excerpt_bytes raising context up to 8192, and private-only cursors. Minor gap: regex, domain, status, maturity, include_history and include_sources are barely touched in the description.

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

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

Opens with a specific verb+resource ('Search saved entries and skills') and immediately distinguishes itself from space_search and the Space tools. An agent can tell what it searches and what it doesn't without reading 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?

Explicit routing: Space tools for Space members/channels, space_search for discussion threads, knowledge_get for the full entry. It also states the fallback behavior when not_searched names the omitted side, and gives query guidance ('2-4 distinctive keywords, not a question').

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 only declare readOnly=false and destructive=true; the description adds the substantive destructive semantics — 'Text and sources are replaced together: include every source to keep, because omitted sources become a single author statement' — which is exactly the data loss an agent must know. It also discloses optimistic-concurrency refusal, the space default and auto-creation, and includes a prompt-injection guard stating text/sources are untrusted reference data, not permission.

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 dense sentences with no filler; the concurrency guard and the source-replacement rule are front-loaded where they matter most. The parentheses and multi-clause sentences make it slightly wall-of-text, but every clause carries operational meaning.

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 write tool with a nested sources array and provenance object, the description covers the failure mode, the replace-all hazard and the write target, and an output schema exists so return values need not be explained. The remaining gap is the provenance/premise_versions semantics, which neither the description nor the schema documents.

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

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

With only 20% schema description coverage across 10 parameters, the description compensates well for the highest-risk ones: expected_version_id (exact current version), sources (replace-not-merge semantics) and space_id (Personal default, auto-create). But it says nothing about provenance (sourced vs inferred, premise_versions/premise_knowledge_ids), kind, path, title or text, leaving a nested object effectively undocumented.

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

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

The description gives a specific verb and resource: 'Save a new version of an entry at its exact current version (expected_version_id)'. The word 'version' implicitly separates it from knowledge_create, but no sibling is named, so an agent must infer the create-vs-update distinction and the relationship to knowledge_propose.

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 tells you the call is 'refused if the entry changed since you read it' and that it writes to Personal Space unless space_id names another, which is useful conditional context. However, there is no explicit when-to-use-this-vs-alternative guidance (knowledge_create vs knowledge_propose), and no stated prerequisite that you must first read the entry to obtain expected_version_id.

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, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real behavioral context by scoping terms_url to usage terms only and flagging that plan, price and purchase details are absent. It doesn't describe the response shape, but an output schema exists so that burden is lower.

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

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

Every sentence carries information, but the opening sentence chains six concepts with 'plus' into a single ~60-word clause, which hurts front-loading and scannability. A short lead ('Returns plan-wide limits and rules metadata') followed by the enumeration would read far better.

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

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

The description covers scope, non-scope, the sibling alternative, and what terms_url contains; the return shape is documented by the output schema. It is complete enough to call correctly, though the enumeration of returned fields is tangled enough that an agent may need a second pass to map 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly implies a parameterless global 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 a specific verb (read) and enumerates the exact resources returned: weekly included Credit coverage, private Space usage rates, available features, terms_url, assistant availability, and request/response limits. It is clearly distinguishable from account_get_usage, which it names. The only drawback is that the first sentence is a dense run-on that takes effort to parse, but the content is precise.

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

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

It explicitly routes the agent: a signed-in person's own coverage comes from account_get_usage, and pricing/purchase questions are out of scope and belong on the O++ website. Both the alternative tool and the when-not condition are stated, with an instruction on what to say 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?

Beyond the readOnlyHint/destructiveHint=false annotations, the description adds real behavioral context: Community methods 'grant no additional permissions, spending or private disclosure authority' and public discussion / reviewed knowledge publication 'retain their own boundaries.' That clarifies what reading does not authorize, which annotations alone would not convey.

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

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

The front-loaded 'O++: start here' is good, but the body crams setup, Spaces onboarding, internal agents, returning-user preference and Community-method boundaries into dense run-on clauses. Several ideas don't directly help an agent invoke this zero-param tool, adding bulk without proportional 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?

With an output schema present and safety annotations covering read-only/closed-world, the description needn't explain return values or safety. It is complete enough for a zero-param onboarding tool, though the multiple tangential purposes weaken focus on the single 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?

Zero parameters and 100% schema coverage, so the baseline of 4 applies. There is nothing for the description to compensate for.

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?

Opening sentence 'O++: start here. Read first to set up, connect...' and 'Return the getting-started guide and recommended skills at one exact shared Git revision' give a specific verb (return) and resource (getting-started guide + recommended skills at a pinned revision). The purpose is clear, though the sentence with 'post publicly or propose knowledge' blends what the user does next into the tool's own action, slightly muddying the boundary.

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

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

It explicitly says to read this first for setup, connection, onboarding, publishing and knowledge proposals, and notes that 'knowledge_search, knowledge_get and skill_get need no setup' — a useful distinction against siblings. It lacks an explicit when-not, but the 'read first' framing gives clear context for selection.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description usefully adds that the skill never self-executes, grants permissions or publishes, plus the side effect of creating Personal Space when needed. That goes meaningfully beyond the annotations. It does not state what happens on a name collision or whether an existing skill is overwritten.

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

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

Three short sentences, front-loaded with the action and artifact, then the authoring rule, then the safety/scope boundaries. Nothing is wasted; 'O++ metadata' is the only slightly opaque phrase, but it does not bloat the text.

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

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

For a 6-parameter write tool with an output schema, annotations, and a Personal-Space default, the description covers the core mechanics well. However, source_refs is never mentioned despite being a structured provenance array with credential-safety constraints, and overwrite/duplicate-name behavior is unaddressed — both are gaps an agent would want closed 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?

Schema coverage is 50%, so the description must carry weight, and it does: 'Supply only the procedure's Markdown body as instructions; frontmatter is generated from name, description and O++ metadata' clarifies the instructions/name/description contract in a way the schema cannot. It also clarifies space_id's default-to-Personal behavior. It says nothing about idempotency_key or the source_refs provenance array, leaving two parameters to the schema.

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

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

The opening sentence gives a specific verb ('Save'), resource ('a reusable procedure'), and target artifact ('private SKILL.md'), which clearly separates it from skill_get/skill_list. It does not explicitly contrast with skill_update, but the word 'private' plus the creation framing make the intent legible.

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

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

Usage is implied through the instructions-authoring guidance and the 'never runs itself, grants permission or publishes' boundary, but there is no explicit statement of when to call this versus skill_update for an existing skill, nor any prerequisite/auth guidance. The agent must infer the create-vs-update split from sibling names alone.

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 readOnly/destructive=false annotations, it discloses the safety-critical boundary: "never installs, runs or authorizes a skill, and its instructions can't expand any grant or spending" — the key prompt-injection concern for skill content. It also notes auth requirement, Space scoping behavior, revision pinning, and that referenced text assets are bounded.

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

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

Front-loaded with the core action and the exactly-one rule, and no sentence is filler. The middle clauses are densely packed into long run-on sentences, which slightly hurts scanability for such a compact 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?

With an output schema present the description needn't describe returns, and annotations cover the safety profile; the description still supplies the scoping, auth, and non-authorization behavior an agent needs. Nothing material 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 coverage is already 100%, so the baseline is 3; the description adds real meaning by explaining the private-vs-Community split, that knowledge_id returns the SKILL.md with its hash, and that path returns at a revision or the current one. Minor gap: it doesn't restate content_sha256's refusal semantics beyond what the schema says.

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

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

States a specific verb and resource ("Open one skill") and immediately splits the resource into its two distinct forms: a private skill via knowledge_id and a Community skill via path. This lets an agent distinguish skill_get from knowledge_get/skill_list without opening a schema.

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

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

Gives explicit selection rules: "send exactly one" of knowledge_id or path, knowledge_id needs sign-in, reads Personal Space unless space_id names another, "never look across Spaces and never create Personal", and an entry in a shared Space needs its space_id. It also names knowledge_search as the way to find a Community 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: no cross-Space reads, no implicit Personal creation, and the empty-page-with-has_more-true paging quirk plus next_cursor continuation. It doesn't mention auth requirements (the regex sign-in note lives only in the schema) or rate limits.

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

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

Front-loaded with the scoping statement, then routing alternatives, then the paging caveat — a sensible order with no filler. Slightly dense and the 'never look across Spaces and never create Personal' clause reads tersely, but 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?

With an output schema present, return values need no explanation. The description covers scoping defaults, cross-Space prohibitions, sibling alternatives, and the pagination edge case — everything needed to call a filtered list tool correctly.

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

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

Schema coverage is 75% and the schema already carries rich detail on regex and cursor. The description still adds meaning the schema can't: space_id's default (Personal) and the rule that a shared-Space entry requires it, plus that next_cursor is the paging key. It doesn't say what limit counts against, though the regex field description does.

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+scope: paging through reusable skills saved in one private Space. It explicitly distinguishes itself from knowledge_search (Community skills) and skill_get (opening one), so an agent can route 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?

Explicit when/when-not guidance: reads Personal Space by default, requires space_id for entries in a shared Space, never looks across Spaces, never creates Personal, and names two alternatives (knowledge_search for Community, skill_get to open one). The only missing piece is what to do if a skill isn't in any Space.

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

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

Annotations only flag readOnly=false, destructive=true, openWorld=false; the description adds the substantive detail behind that destructiveness — frontmatter is regenerated (custom frontmatter lost), the supplied name/description/instructions must be complete replacements, and a Personal Space is written/created as a side effect. Those are exactly the consequences an agent must know before a destructive write.

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, purpose first, then the alternative path, then the space side effect — no filler. It is dense and packs several clauses per sentence, which costs a little readability but not correctness.

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 an output schema present the description needn't explain returns, and it covers the mutation semantics and space default well. The notable gap is source_refs: for a full-replacement write, an agent is not told whether omitted source_refs are dropped, which matters given destructiveHint=true.

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 38%, so the description must carry more weight, and it does explain the space_id default ('Personal Space unless space_id names another, creating Personal when needed'). However, expected_version_id is only named, never explained as an optimistic-concurrency check, and source_refs and idempotency_key are not addressed at all in the description.

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

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

States a specific verb and resource ('Save a new version of a private skill') and immediately names the exact inputs that define the operation (knowledge_id, expected_version_id, complete name/description/instructions). It distinguishes itself from knowledge_update, the closest sibling, in the same sentence.

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 routing rule: if you need to preserve custom frontmatter, use knowledge_get + knowledge_update instead. That is a concrete when-to-use-alternative statement. It does not say when to choose skill_create vs skill_update, leaving that boundary to the name.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context by revealing that the general-link branch only creates an approval request rather than immediate membership, but says nothing about failure cases, idempotency, or what membership state results.

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

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

Two sentences, no filler, with the dual-mode behavior stated first and the parameter constraint stated last as the operative rule. Every sentence carries information an agent cannot get from 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?

Output schema and annotations cover return values and safety, and the description covers the mutual-exclusivity rule. Still missing: what happens if neither parameter is supplied (required is 0) and which identifier corresponds to the direct-invitation versus general-link path, which is exactly the ambiguity an agent would hit.

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

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

Schema description coverage is 0%, so the description must compensate. It does add the critical 'exactly one of' exclusivity constraint that the schema does not encode (both params are optional with no oneOf), but it does not explain which identifier belongs to which flow or why the patterns differ (iv_ vs i_).

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?

Uses a concrete verb+resource (accept an invitation) and explicitly splits the behavior into two modes: accepting a direct invitation versus requesting owner approval for a general link. This distinguishes it functionally from space_approve_invitation and space_preview_invitation, though it never names those siblings.

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

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

The two branches ('addressed to you' vs. 'general link') give a clear condition for choosing each flow, and the final sentence gives the argument-selection rule. It stops short of routing to alternatives such as space_approve_invitation or space_list_invitations.

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 that this is a destructive mutation, so the safety profile is covered. The description adds the owner-role requirement and the invite-link context, but it does not explain what declining does, whether approval grants immediate access, or any irreversible consequences.

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 a single front-loaded sentence with no wasted text. It is appropriately sized for the tool's name and title.

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

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

An output schema exists, so return values need not be described. However, for a three-parameter destructive mutation with no schema descriptions, the description is too thin: it omits the semantics of the approve boolean and the effect of each choice.

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?

All three parameters have zero schema description coverage, and the description does not clarify them. In particular, it does not explain that the 'approve' boolean chooses between approving and declining, nor does it describe the expected format or meaning of space_id and invitation_id.

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 pair (approve or decline) and a specific resource (someone who used your general invite link) scoped to the Space owner. It implicitly distinguishes this from accepting an invitation yourself or directly inviting a member, though it does not name any sibling 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?

The phrase 'As the Space owner' and 'someone who used your general invite link' gives clear context for when this tool applies. It does not include explicit exclusions or name alternative tools such as space_preview_invitation or space_list_invitations.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing that the public path returns a pending request rather than a Space, that sign-in or a linked agent is required, and that both paths are retry-safe when the same idempotency_key and arguments are reused. Those are exactly the behaviors an agent cannot infer from structured fields.

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

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

Four dense sentences with the default behavior front-loaded, followed by the exception, the retry contract, and the auth requirement. No filler, and the ordering matches how an agent decides how to call 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?

An output schema exists, yet the description still flags the non-obvious return semantic (pending request, not a Space) that the schema alone would not convey. With auth, idempotency, and both modes covered, an agent has everything needed to call it correctly on the first try.

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 baseline is 3; the description adds narrative value by tying public=true to the purpose requirement and the 80-character title cap, and by spelling out the idempotency contract (same key + same args on retry). It mostly restates schema text, which keeps it below a 5.

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

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

Specific verb+resource ('Create a Space') with both operating modes named and contrasted: an immediate private Space vs. a moderated Community Space request. It also names the sibling (space_get_request) that continues the workflow, so an agent can place the tool in the lifecycle 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?

It states the default path (private, you as owner) and the condition that switches behavior (public: true, which requires purpose), plus where to read the outcome. It stops short of naming alternatives or when not to use it — e.g. it never mentions space_ensure_personal for the personal-space case — so routing is clear but not exhaustive.

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

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

Annotations already declare a non-destructive, non-open-world write; the description adds genuinely new security context by stating the token "grants no Space or direct-message access," which tells the agent what privilege the artifact does not confer. It omits other traits an agent might need, such as token expiry, single-use vs reusable behaviour, and whether creating a new one invalidates prior tokens.

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 purpose comes first and the most safety-relevant constraint (no access granted) follows immediately. Nothing is padded or restated from 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 parameters and an output schema covering the return value, the description is nearly complete — purpose plus privilege scope is the core information. A note on token lifetime or shareability would close the remaining gap for a credential-producing 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?

Zero input parameters, so the schema leaves nothing to explain and the baseline applies. The description correctly adds no parameter detail, since none exists.

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?

A concrete verb+resource ("Create a token") plus a precise gloss of what the token is for (a Space owner uses it to invite you). The agent can tell this apart from space_invite_member or space_resolve_contact_link, though the counterpart tool that consumes the token is never 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 description shows the scenario — hand the token to a Space owner so they can invite you — which implies when to call it. It does not explicitly route the agent away from anything (e.g. that this is not an invitation-acceptance tool, or that space_resolve_contact_link is the receiving side), leaving the alternative-selection logic 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?

The description usefully explains why readOnlyHint is false despite the read-flavored name — the call may create the space — and confirms the operation is non-destructive in intent. The clause about knowledge using the existing private account scope adds real behavioral context about data ownership. Idempotency and concurrency behavior are left implicit.

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 primary action and immediately qualified by the conditional side effect. No filler, no restatement of the title.

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

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

With zero parameters and an output schema covering the return shape, the description carries everything an agent needs: what it returns, that it may create, and what scope the resulting knowledge lives under. Only explicit idempotency/repeat-call guidance is missing.

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

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

The tool takes zero parameters, so the schema has nothing to document and no description-side parameter guidance is needed. Baseline for a no-param tool.

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 pair ("Return your account's Personal Space") and adds the qualifying behavior "creating it if it doesn't exist yet," which makes the ensure/upsert semantics unambiguous. It does not explicitly name space_create or space_get as the alternatives it replaces, so sibling differentiation is implied rather than stated.

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

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

The create-if-missing framing gives clear context for when to call it: any time you want the personal space without first checking existence. It stops short of explicitly stating exclusions (e.g. use space_create for non-personal spaces, or space_get for a read-only lookup).

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 that this is a non-destructive write in a closed system, and the description adds meaningful context: the idempotency key requirement and the need for access to both source and destination Spaces. It stops short of describing conflict or overwrite behavior, so it is strong but not complete.

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 zero wasted text. The core action is front-loaded, followed by the key access prerequisite.

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 annotations and an output schema already present, the description covers the essential purpose, access prerequisite, and idempotency requirement. A note about what happens if the destination already contains the file would make it fully complete, but the remaining gap is minor.

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

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

Schema description coverage is only 20%, so the description must compensate, and it does conceptually clarify file version, source Space, destination Space, and idempotency. Still, it adds little detail about file_id/version formats or Space ID constraints beyond what the schema already shows.

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 ('Copy') and resource ('an exact file version') and clarifies the destination is another private Space. It is clearly distinct from space_file_create in intent, though it does not explicitly name or contrast with that 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?

It gives a useful prerequisite — current access to both Spaces — and implies usage when copying an exact file version between spaces. However, it does not explicitly say when to use this instead of space_file_create or space_file_get, leaving selection partly inferred.

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

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

Annotations already declare non-readOnly, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by stating the 4 MiB decoded-byte ceiling and that content is 'kept without parsing or executing it' — a security-relevant guarantee not in the schema. It does not mention permission requirements or what happens on idempotency-key reuse (that detail lives only in the schema).

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

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

Two dense, front-loaded sentences with the size ceiling and encoding stated up front. Slight redundancy between 'opaque file' and 'without parsing or executing it', but both clauses carry usable information.

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

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

With an output schema present, return values need no explanation, and the description covers the crucial operational facts (size cap, encoding, idempotency, opaque storage). Remaining gaps — sha256 semantics and the private-Space access precondition — are minor but real for a 6-parameter mutation tool.

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

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

Schema description coverage is only 33%, but the description compensates for the most important gaps by specifying canonical base64 encoding and the 4 MiB decoded limit for data_base64, plus the stable-key nature of idempotency_key. It says nothing about sha256 (undocumented in the schema) or media_type defaults, so coverage remains partial.

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

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

States a specific verb and resource ('Store an opaque file') plus the scope ('in a private Space') and a hard size limit, so the agent knows exactly what the call does. It does not explicitly distinguish itself from siblings like space_file_copy or space_file_get, leaving that inference to the agent.

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 phrase 'using canonical base64 and a stable idempotency key' hints at the required write pattern, but there is no explicit when-to-use/when-not or comparison to alternatives such as space_file_copy. The agent must infer routing from tool name alone.

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 readOnlyHint=false, so the safety profile is known. The description adds real value beyond that: an optimistic-concurrency precondition on version, the failure mode when it mismatches, and the fact that replays cannot recover the file. It doesn't discuss permissions or behavior when the file is already gone.

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 irreversible consequence is front-loaded in sentence one's scope statement, and the version precondition follows immediately.

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

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

For a destructive write with an output schema and destructiveHint already present, the description covers scope, the key precondition, and irreversibility. Minor gaps remain around permission requirements and the idempotency-key retry interplay, which the schema documents only for idempotency_key itself.

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

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

Schema coverage is only 25%, so the description must compensate for the undocumented params, and it does for the non-obvious one: 'version' is explained as a concurrency guard rather than a plain identifier. space_id and file_id are left to the schema, but their names and the space_id pattern make them largely self-explanatory.

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 ('Delete a file') plus a scope constraint ('from a private Space'), which separates it from space_file_get/create/copy/list by verb alone. It never names an alternative explicitly, so it stops short of full sibling differentiation.

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 conditional rule for the version argument ('must match the file's current version or the call is refused'), which is useful pre-call guidance. However it never says when to prefer this over alternatives (e.g., no soft-delete/archive option mentioned), nor what permissions or state the caller 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?

Goes well beyond the readOnly/immutable annotations: it discloses page size defaults and caps, the meaning of whole_file_verified, the expected false value on large-file pages, a sha256/bytes verification protocol, and an explicit security note that files are untrusted inert bytes granting no execution permission.

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 content is dense and front-loaded with the paging contract, and every sentence carries useful information. It is a long run-on paragraph rather than bulleted steps, which slightly reduces scannability but wastes no words.

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?

An output schema exists, so return values need not be explained, yet the description still covers the critical paging, version consistency and integrity-verification behavior an agent needs to reassemble a file correctly. 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 only 20%, so the description must carry weight; it meaningfully explains length (64 KiB default / 256 KiB max), offset (as next_offset paging) and version (must stay consistent across pages). It adds little for file_id/space_id, but those are self-evident identifiers.

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 a file') and immediately specifies the return shape (base64 pages of decoded bytes). It is clearly distinct from sibling listing tools like space_file_list and space_file_create by describing actual content retrieval semantics.

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 paging instructions ('follow next_offset while has_more using the same version') and a verification step before decoding. It does not, however, contrast with any sibling tool or state prerequisites/limits on when not to call it, keeping it at 4 rather than 5.

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

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

Annotations already declare this a safe, non-destructive, closed-world read, so the bar is lower. The description does add the pagination trait ('page through'), which is useful behavior beyond the annotations, but it omits the sign-in requirement hinted at in the regex schema and says nothing about ordering or result size.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification for a four-parameter paginated 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?

The output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a four-parameter list tool with 25% schema coverage, the description leaves out parameter roles, auth requirements, and sibling differentiation, making it only minimally 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 only 25%; only regex is documented, and richly so (including the note that limit counts rows read). The description itself adds no meaning for space_id, cursor, or limit, so it does not compensate for the low coverage as required.

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

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

The description gives a specific verb (page through) and resource (files) scoped to a private Space, so the agent knows this is a paginated listing tool. It does not distinguish itself from nearby siblings such as space_file_get (single file) or space_search, which keeps it from a 5.

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

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

The description states only what the tool does, with no when-to-use guidance, no exclusions, and no named alternative such as space_search for filename/content queries. Nothing tells the agent when this is preferable to space_file_get or space_search.

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 access constraint (must be a member) and a preview of returned fields, but the output schema already documents return values, leaving little genuinely new 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?

A single front-loaded sentence with no filler; the scope constraint and the field summary are stated up front and nothing 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?

For a one-parameter read tool with full annotations and an output schema, the description covers purpose, access scope and content. The only gap is not explaining the single required parameter or its source, which is minor given the existing pattern constraint.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, yet it never mentions space_id or where to obtain one. The schema's regex pattern conveys the expected format, but the description does not compensate with guidance such as sourcing the ID from space_list.

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 a private Space') and enumerates the salient return fields (owner, your role, actor ID). It is clearly distinguishable from space_list, though it never explicitly names that sibling as the alternative for listing.

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?

'A private Space you belong to' implies a membership prerequisite, which is useful usage context. However, it gives no explicit when-to-use/when-not guidance and does not route the agent to space_list, space_get_actor, or space_resolve_contact_link for related lookups.

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, openWorld, non-destructive), and the description adds substantial context beyond them: the exact default behavior for each omitted parameter, that registered_at is absent when registered is false, that a linked agent receives the registration_id needed by agent_grant_set, and that private-Space actor IDs only resolve within that Space. That is exactly the cross-tool and scoping information annotations cannot express.

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

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

The core purpose is front-loaded in the first clause and every subsequent clause carries real information about defaults, return shape, and auth. It is dense and runs as one long block rather than separated points, which slightly hurts scanability but wastes no words.

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 an output schema present, return values need not be described, yet the description usefully flags the conditional fields (registered_at, registration_id). Combined with the auth requirement, default-parameter behavior, and Space scoping, an agent has everything needed to invoke this correctly in one shot.

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 still adds meaning by explaining the semantics of omission for both parameters ('you' for actor_id, Community for space_id) and the private-Space restriction on space_id values. It does not add format or pattern detail beyond the schema, so it sits just above baseline.

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

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

States a specific verb and resource — 'Look up one registered actor' — and the singular framing separates it from the plural sibling space_list_actors without naming it. The added 'for example before mentioning it' gives a concrete reason to call it. It does not explicitly name the sibling it supersedes, 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?

Gives clear calling contexts: use it before mentioning someone, omit actor_id to get yourself, omit space_id to target Community, and private-Space IDs are scoped to that Space. It also states the auth prerequisite ('sign-in or a linked agent'). It never names an alternative tool or a when-not-to-use condition, which keeps it at 4.

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=true, so the safety profile is covered without the description. The description adds that the response carries status and reason and that only the caller's own requests are visible, but says nothing about behavior for missing or foreign request IDs.

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, front-loaded with the verb and resource, with the ownership scope and ID provenance folded in without padding. Nothing is wasted and nothing needs reordering.

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 annotations covering safety and an output schema covering return shape, the description only needs to establish scope and ID provenance, which it does. The remaining gap is error behavior for unknown or non-owned request IDs, which is minor for a simple read.

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

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

The single request_id has 0% schema description coverage, so the description carries the burden, and it does the most important part by telling the agent where the ID originates (space_create or space_request_channel). The ID format is only conveyed by the schema's regex pattern, which the description does not restate.

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

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

The description gives a specific verb (read) and a precisely scoped resource (status and reason of your own Space or channel request), and it names the two producing tools (space_create, space_request_channel), which separates it from space_get and the listing tools. It stops short of naming an alternative tool an agent might confuse it with, so it is clear but not sibling-differentiating in the strongest sense.

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?

'Your own ... request' implicitly excludes requests belonging to other actors, giving a real usage boundary. It does not state what to do if the request is not yours or is still pending, and it names no alternative tool, so guidance is clear but not exhaustive.

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

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

Beyond the annotations, the description discloses that no email is sent, the invite_url must be shared manually, a general link is invisible in the recipient's inbox until they request access, and that previewing does not constitute a request. These are non-obvious behavioral facts an agent needs before invoking a write.

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 in the first clause, followed by compact clauses covering return value and lifecycle caveats. Some sentences are terse to the point of being cryptic ('Pending is not membership'), 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?

The tool is a non-destructive write with an output schema, so return values need little explanation; the description nonetheless notes invite_url. With the idempotency contract in the schema, the main remaining gap is undocumented format for space_id/contact_token.

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

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

Schema description coverage is only 33% – only idempotency_key is documented in the schema. The description implies contact_token identifies a recipient and space_id is a space you own, but adds no format or constraint detail for these two required-ish parameters, so it only partially compensates.

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+resource ('Invite a contact-token recipient to a private Space') and distinguishes two operating modes: targeted invite vs. a general invitation requiring approval. It does not name sibling tools like space_create_contact_link or space_preview_invitation, so it stops short of full sibling differentiation.

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

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

It clearly states the two conditions under which the tool is used (contact-token recipient vs. general link requiring your approval) and clarifies lifecycle semantics ('Pending is not membership', 'Previewing the link does not request access'). It lacks explicit routing to the alternative tools an agent might pick instead.

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