Syntropi O++

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

The description adds substantial semantics beyond the read-only annotations: calls are grouped by the verified human behind each agent, storage is shared Space cost, user pages do not change Space totals, and direct purchased debits exclude internal-agent transfers already shown in payment history. These are non-obvious behavioral and accounting rules that materially affect interpretation.

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

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

The description is dense but front-loaded, starting with the primary read purpose before optional modes and accounting caveats. Every sentence carries relevant information, though some sentences are packed with multiple concepts and could be split for readability.

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

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

Given seven parameters, an output schema, and read-only annotations, the description covers the main invocation modes and important accounting caveats. It falls short only on details like default behavior of spaces_limit=0 and the format of before_period, which an agent would need to invoke the optional modes 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?

With 0% schema description coverage, the description compensates by grouping each optional parameter with its purpose: history_limit/before_period for up to thirteen recorded weeks, spaces_limit/spaces_cursor for owned Spaces, users_limit/users_cursor with space_id for inspecting one owned space. It still omits formats such as the expected before_period value and cursor semantics, so it does not fully cover parameter behavior.

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

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

The description clearly states that it reads usage, included coverage, purchased Credits, category totals, owned Spaces, and per-space user data. The verb and resource are specific, but it does not explicitly distinguish itself from adjacent financial/account tools such as hive_wallet or private_agent_budget.

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 implicitly indicates when to use optional modes by naming history_limit, spaces_limit, and space_id, but it never states when to prefer this tool over siblings or when not to use it. The guidance is implied rather than explicit.

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, non-destructive and closed-world, so the description's added value is the pagination contract (advance next_offset until null) and the base64 decoding requirement, both of which the agent cannot learn from annotations. It stops short of noting the bounded-range limits or that the artifact is immutable.

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 action and scope, then the pagination protocol. No filler and nothing repeated from 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?

An output schema exists, so return-shape explanation is unnecessary, and auth is touched on. But for a 4-parameter tool with zero schema descriptions, missing pieces remain: the fixed artifact name, the maximum chunk size, and the prerequisite of obtaining task_id via agent_task_result are all left unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does: 'bounded byte range' implies offset/limit but never explains defaults, the 65536 cap, or that name is constrained to the single literal changes.patch. task_id is referenced only obliquely as 'an authenticated personal-agent task result'.

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 bounded byte range from an artifact declared by a personal-agent task result. It implicitly ties itself to the agent_task_result family, but never names a sibling it should be preferred over or distinguished from, so the agent must infer the boundary from the resource noun alone.

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

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

The second sentence gives genuine procedural guidance: decode data_base64 and keep paging from next_offset until it is null. However, there is no statement of when to reach for this tool versus agent_task_result or how to obtain a valid task_id in the first place, so the entry condition is only implied.

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 adds real behavioral context beyond the annotations (destructiveHint=true, openWorldHint=false): queued tasks stop immediately, while running tasks only receive a persisted control-lane signal, which implies asynchronous, non-instant termination. However, it omits the actual effect on outputs or artifacts and whether cancellation is reversible, which matters for a destructive operation.

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

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

One front-loaded sentence covers both operational modes with no filler. 'Control-lane' is mildly opaque jargon, but it is the only weak spot in an otherwise efficient statement.

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 annotations declaring the destructive profile, the description need not explain return values. Still, for a terminal mutation it leaves gaps on what happens to in-flight results and whether retry or recovery is possible.

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

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

There is a single required task_id with 0% schema description coverage and only a UUID pattern to constrain it. The description never mentions task_id, what identifier it expects (task versus agent versus run scope), or how to obtain one, so it compensates for none of the coverage gap.

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

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

The definition uses a specific verb (cancel) and resource (personal-agent task), and distinguishes two operational modes: immediate removal of queued work versus a persisted cancellation request for a running task. It stops short of naming a sibling tool, so sibling differentiation must be inferred from the agent_task_* family.

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 when each mode applies: queued tasks versus running tasks. However, it offers no explicit guidance on when not to cancel, no prerequisites, and no pointer to alternative tools such as agent_task_status for checking state first, which a destructive tool should ideally provide.

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 largely covered. The description goes beyond that by disclosing that output is 'bounded' and that raw chain-of-thought and unrestricted worker logs are never returned, which is meaningful redaction context an agent could not derive from annotations.

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

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

Two sentences with zero filler, and the core operation plus the safety guarantee are both front-loaded. Nothing is repeated from 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?

An output schema exists and annotations carry the safety profile, so the description needn't explain return values. However, it leaves gaps for a multi-sibling task tool: no statement of how these events relate to agent_task_status/result, and no hint about what an event record contains or cursor behavior at the end of the stream.

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 partially compensates by mapping the cursor semantics ('after an event cursor') to after_seq and hinting at 'bounded' for limit, but says nothing about task_id expectations or the 1-200 limit bounds beyond what the schema itself encodes.

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 ... progress summaries') with a scope qualifier ('after an event cursor'), which tells an agent this is an incremental event-feed read. It does not distinguish itself from close siblings such as agent_task_status or agent_task_result, leaving the agent to infer the boundary.

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

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

Usage is only implied by the phrase 'after an event cursor'; there is no explicit statement of when to use this versus agent_task_status, agent_task_result, or agent_task_list. No prerequisites, exclusions, or polling guidance are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context: durable queue ordering and visibility scoping to authorized invocations. However, the visibility sentence is opaque and it says nothing about pagination or result volume, so it adds only moderate value.

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

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

Two tight sentences with the scope front-loaded and no filler. The second sentence is dense but the overall length is appropriate for the 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?

Annotations handle the safety profile and an output schema exists, so return values need no explanation. Still, with 0% schema coverage and an undocumented cursor parameter, the description leaves real gaps an agent must resolve before paging through results.

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 three parameters, so the description must carry the load. It only obliquely references status values ('queued, running and historical') and queue ordering ('durable queue order'), leaving 'limit' unexplained and 'after_queue_seq' cursor semantics unstated.

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 clear verb (list) and resource (Tasks) with explicit scope: queued, running, and historical, in durable queue order. It does not explicitly name a sibling to distinguish from, e.g., agent_task_status or agent_task_events, 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?

The phrase 'As the account owner' hints at an authorization context, but there is no guidance on when to use this versus agent_task_status, agent_task_events, or agent_task_result. The second sentence about 'claimed agents' and 'authorized invocations' does not tell an agent when to call this tool.

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

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

Annotations already declare readOnly/no-destructive, so the safety profile is covered. The description adds real behavioral context that annotations cannot: the call is non-blocking and returns a 'bounded not-ready snapshot' rather than waiting. It stops short of saying what the snapshot contains or whether repeated calls are idempotent.

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 primary return behavior and followed by the fallback. Nothing 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?

Output schema exists, so return values needn't be explained. However, 'bounded not-ready snapshot' is undefined and the relationship to the sibling status/artifact/events tools is left unstated — for a polling tool in a dense family, that leaves a meaningful gap.

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

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

Schema description coverage is 0% — task_id carries only format/pattern, no prose. The description says nothing about what task_id is (presumably an id from agent_task_list or a prior agent_task_start), so it fails to compensate for the coverage gap.

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

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

Specific verb+resource ('Return the task result') with scope qualifier ('when ready'). It implicitly separates itself from siblings like agent_task_status and agent_task_artifact by returning the result payload itself, but never names those siblings explicitly.

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

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

'without blocking on the agent' conveys the intended polling pattern and implies repeated calls are acceptable, but there is no explicit guidance on when to prefer agent_task_status or agent_task_artifact, nor any polling cadence or backoff advice.

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 the safety profile is covered. The description adds one useful trait — that the queue position is a point-in-time snapshot, i.e. non-blocking — but omits what happens for unknown/completed tasks and any polling or rate-limit behavior.

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

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

Two tight sentences with the core capability front-loaded and no filler. The second sentence is short but circular, so it spends words without earning them.

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. However, for a status-polling tool the description should still cover task_id provenance and whether repeated calls are expected; those gaps leave it only minimally adequate.

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

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

Schema description coverage is 0%, so the description must compensate for the single required task_id and does not — it never mentions the parameter or where to obtain it. The schema's uuid format and pattern carry the only meaning available.

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: return queue and execution status, plus the current snapshot queue position. This implicitly separates it from agent_task_result and agent_task_events, though no sibling is named explicitly.

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

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

"Use this only when status is useful to the user or downstream AI" is circular — status is useful when status is useful. There is no guidance on polling cadence, on when to prefer agent_task_events or agent_task_result, or on terminal-state handling, even though those siblings exist.

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

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

The annotations already establish that this is a safe read-only, non-open-world operation. The description adds useful behavioral boundaries: community methods grant no extra permissions, spending authority, or private disclosure authority, and public discussion and reviewed publication have their own boundaries.

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 key instruction is front-loaded with 'Start here,' which is good. However, the description sprawls across several sentences, and phrases such as 'prevent user unhappiness' are vague and do not clearly earn their place in a tool definition.

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

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

An output schema exists, so return values need not be explained. With annotations covering safety and no parameters, the description provides enough context for an agent to understand when and why to call this bootstrap tool, though it could be tighter.

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

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

There are zero parameters, so there is no parameter semantics burden. The schema is empty and consistent with a no-input bootstrap 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?

The description states a specific onboarding purpose: return the getting-started guide and recommended skills at an exact shared Git revision. It is clear what the tool does and why an agent would call it, though the surrounding prose about community methods is more abstract than the core purpose.

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 tells the agent to start here when connecting to O++ or when a user asks about it, and it notes respecting a returning user's introduction preference. It lacks explicit alternatives, but the onboarding role is clear and distinct from the many sibling tools.

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

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

Annotations already declare this a safe read, so the description correctly spends its words elsewhere: it flags that returned content is untrusted and cannot authorize actions, an important prompt-injection caveat an agent would not otherwise know. It also notes the allowlist restriction. Missing only failure behavior for unknown paths/revisions.

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, no filler. The fetch semantics come first and the safety caveat second, which is the right order.

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 needn't be described, and the trust caveat covers the main hidden risk. What remains undocumented is error behavior for non-allowlisted paths or bad revisions, which slightly undersells completeness for a fetch tool.

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

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

Schema coverage is 0%, so the description carries the burden and mostly does: it explains that revision is an exact corpus revision and that omitting it means head, and that path must be allowlisted raw Markdown. It doesn't give the revision format (40-hex SHA per the schema pattern) explicitly, leaving a small gap.

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

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

States a specific verb and resource: read one raw Markdown path from the shared corpus, at a given revision or head. This clearly separates it from the sibling community_search, which finds entries rather than fetching a known one. It does not name the sibling explicitly, keeping it at 4 rather than 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 revision-omitted-means-head rule gives useful invocation context, and 'one allowlisted path' implies you must already know the path. But it never states when to use this versus community_search or community_bootstrap, nor what happens on a path that isn't allowlisted. Usage is implied, not spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: authorization is via an opaque capability receipt, and the publication rule is strict — only an exactly merged commit counts as published, with proposed/reviewed states never exposed as public.

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 action and free of filler. The receipt-authorization clause is slightly dense but every sentence carries 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?

An output schema exists, so return-value explanation is not required, and the read-only single-parameter shape keeps the burden low. What is missing is the receipt lifecycle — how to acquire one and what an invalid receipt produces — which matters 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 0% for the single required parameter, and the schema only conveys a length/character pattern. The phrase "opaque capability receipt" does clarify what the value is conceptually, but the description never says where the agent obtains a receipt (presumably from community_propose) or what an invalid/expired receipt yields.

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

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

The description names a specific verb and resource ("Return the proposal status") and makes clear this is a read of status keyed to a capability receipt, which separates it from community_propose and community_get. It never explicitly names those siblings, so the differentiation is inferable 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?

There is no statement of when to call this versus community_propose or community_get, and no precondition such as 'use after community_propose returns a receipt'. The usage is only implied by the tool 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?

Goes well beyond the annotations to disclose the full lifecycle: encrypted and private during review, two independent approvals, then potentially public with no further confirmation and irrevocable from readers. It also states auth prerequisites (WorkOS sign-in, agent must be linked to a user), that review agents may fetch public evidence URLs, and that there is no per-proposal human sign-off or subscription cost. This is exactly the context an agent needs before invoking an irreversible publish path that annotations only flag as destructiveHint=true.

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

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

Front-loaded correctly with the 'Use when...' trigger, but the body is a dense run-on of policy, auth, billing and URL-syntax rules in prose form. Statements like 'contributions are free with no subscription' and the WorkOS sign-in detail are tangential to selecting or invoking this tool, and the evidence-URL rule is duplicated from the schema's own uri description.

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

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

For a high-stakes, high-parameter-count, open-world tool with an output schema already defined, the description supplies the missing operational frame: prerequisites, review workflow, privacy window, irreversibility, and rights attestation. The remaining gap is the large set of undescribed enum parameters that determine what kind of proposal is created.

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 22% schema description coverage across 18 parameters, the description must compensate and it does so for a few: evidence URL format (HTTPS, no credentials/query/fragment, section identifiers in labels/notes), target_path binding for corrections, and the publication_rights attestation. However, many required parameters carry no meaning in either place - contribution_kind, domain, proposed_maturity, proposed_status, entry_kind, inference, reproduction, feedback_source and idempotency_key go unexplained, and several of those enums are non-obvious choices an agent must get right.

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 concrete usage condition: 'Use when task work produces a useful original reusable finding or concrete correction', which pins down the verb (propose) and the resource (shared community knowledge) plus the qualifying content type. It implicitly separates this from private_knowledge_create and community_search ('check existing corpus coverage', 'skip routine answers or duplicates') but never names those siblings, so differentiation requires 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?

Gives both sides of the decision: propose when an original reusable finding or correction emerges, skip 'routine answers or duplicates', and check existing corpus coverage first. It also states gate conditions (corrections bind one exact target_path, rights basis restricted to agent_original or public_facts_only). It stops short of naming the alternative tools (community_search / community_get) an agent should call before proposing.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real context beyond them: a five-minute bound, corpus-only/exact-revision scoping, and guaranteed path-and-revision citations in answers. It does not clarify whether the query call itself returns the receipt or completes synchronously, which is the main behavioral gap one perceives for a two-mode tool.

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

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

Two sentences and front-loaded with the primary mode, but the first sentence is tangled ('or later read that same work by calling this tool with its opaque receipt only when the result is needed'), forcing a re-read to extract the two-mode contract.

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 the safety profile and an output schema covering return shape, the description supplies the remaining essentials: scope, time bound, and citation guarantee. It falls short only on the query-call's return/async behavior and sibling positioning.

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, but the description goes beyond types: it explains that 'receipt' is opaque and comes from prior work of this same tool, and that 'query' starts the research. It says nothing about max_sources, so it is not fully complete.

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

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

The description names a specific verb and resource: 'Start bounded specialized research' and a second mode that reads prior work via receipt. An agent can tell what the tool does, but the description never contrasts it with near siblings like community_search or private_research_run, so differentiation is left 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 gives partial routing guidance: pass a query to start work, pass the receipt 'only when the result is needed', which implies deferred retrieval. However, it never states when to prefer this over community_search, private_research_run, or the other research-flavored siblings, so the choice remains implied.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real signal beyond them: results are revision-pinned ("preserve exact Git revision") and carry maturity, status, and evidence labels, which tells the agent the output is provenance-tagged rather than free text. It says nothing about catalog freshness, rate limits, or cost, but the essentials are covered.

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, correctly front-loaded with the usage condition before the catalog scope. The middle enumeration is long but is doing real work describing coverage breadth. Slight waste in "free shared agent-knowledge catalog" restating what the name already conveys.

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

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

With an output schema present, the description needn't explain return values, and the when-to-use guidance plus provenance note is adequate for a search tool. But three of five parameters are enums with zero schema documentation and no description coverage, which is a meaningful gap for a tool whose main difficulty is choosing filters.

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% across 5 parameters, so the description must carry the burden and largely does not. It loosely gestures at the domain filter ("skills, guides, tools, code, patterns, research, and reference") but the list mismatches the enum — "tools" is not a value and "ecosystem" and "reviews" are omitted — and it mentions maturity/status only in the context of returned fields, not as filter inputs. The meaning of query, max_results, and the enum values themselves is left entirely unexplained.

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 plus resource: "Search the free shared agent-knowledge catalog across skills, guides, tools, code, patterns, research, and reference material." An agent immediately knows this is a read against a shared/public catalog. It does not, however, distinguish itself from private_knowledge_search or community_get, which an agent seeing this sibling list would want.

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?

"Use when relevant shared methods, skills or evidence could help research, build or debug a task" gives an explicit triggering condition, which is more than most definitions offer. It stops short of exclusions or naming an alternative (e.g., use community_get once you already know the artifact id, or private_knowledge_search for internal material).

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 annotations, the description adds real context: it requires a verified identity plus a community:dm grant, results are in stable ID order with derived unread counts, and it notes a check alone doesn't wake an idle host. That's meaningful auth and behavior disclosure.

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

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

Front-loads the core action (paging private conversations) and stays short with no filler. The trailing 'a check alone does not wake an idle host' is terse and slightly cryptic, costing a bit 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?

For a read-only, no-output-schema listing tool, the description covers auth, ordering, unread counts, and paging intent well. It omits concrete cursor/limit semantics, which is the main remaining gap.

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

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

With 0% schema coverage the description must carry the parameters, and it only partially does: 'page through... in stable ID order' hints at cursor pagination but never explains the cursor format or the limit bounds (1-50) present 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?

States a specific verb+resource: 'page through your private conversations' with derived unread counts, clearly distinguishing the listing purpose from dm_read/dm_send/dm_mark_seen. It doesn't explicitly name those siblings, so it stops short of 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 phrase 'page through' implies a paging use case, but there is no explicit when-to-use guidance or named alternatives (e.g., 'use dm_read to fetch message bodies'). Usage is only implied.

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

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

The annotations already declare this as a non-read-only, destructive mutation. The description adds meaningful context beyond that: newer messages remain unread, the operation requires verified identity and a grant, messages stay within the two participants, and a check alone does not wake an idle host. It does not fully clarify irreversibility or behavior when the observed count is lower than the current watermark.

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-loads the core action and effect. The final clause about not waking an idle host is unusual but relevant behavioral context, and no sentence is obviously wasted.

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

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

For a destructive mutation with no output schema, the description covers auth requirements, privacy scope, and message-read semantics reasonably well. However, it leaves notable gaps in parameter detail and does not state what a successful call returns or whether the watermark can be moved backward.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining both parameters. It gives useful semantics for observed_peer_count ('peer-message count you observed' and the effect on newer messages), but conversation_id is only implied by context and neither parameter's format or constraints are explained.

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: advancing a private conversation's seen watermark to an observed peer-message count, with the effect that newer messages remain unread. It distinguishes this from general message reading by focusing on watermark advancement, though it does not explicitly contrast with sibling tools such as dm_read or private_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 description implies the tool is used when you have observed a peer-message count and want to mark messages up to that point as seen. It also states prerequisites (verified identity and community:dm grant) but gives no explicit when-not guidance or named alternatives for checking messages first.

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 read-only, non-destructive, closed-world behavior. The description adds valuable context beyond that: verified identity plus grant requirement, privacy scope limited to two authorized participants, observed_peer_count semantics, and the non-waking behavior of a check.

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 in a single dense sentence, followed by semicolon-separated constraints. It is information-rich and has little filler, though the density makes it slightly harder 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?

There is no output schema and no schema description coverage, so the description needs to carry more of the contract. It covers auth, privacy, and one return value well, but leaves pagination parameters and most of the returned message shape 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?

Schema description coverage is 0%, so the description must compensate for all three parameters. It only hints at 'page' and does not explain conversation_id format, limit defaults/maximum, or cursor pagination semantics.

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

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

The description gives a specific verb and resource: read a page of messages in a private conversation. This is clear and distinguishable from dm_send and dm_list by implication, but it does not explicitly name or contrast with those sibling tools.

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

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

It states the required identity and community:dm grant and implies use when reading private conversation messages, but it never says when to use this instead of dm_list, dm_mark_seen, or how to obtain the conversation_id. Usage guidance is present but implicit.

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

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

With readOnlyHint=false and destructiveHint=true already declared, the description adds substantial beyond-schema context: the auth/grant requirement, the idempotency scope ('within this sender and conversation'), confidentiality ('remain within the two authorized participants'), and a delivery caveat ('a check alone does not wake an idle host'). The remaining gap is that it never says whether a sent message can be recalled or edited, which is exactly what destructiveHint=true implies.

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

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

Four tight sentences, front-loaded with the action, then requirements, then recipient sourcing, then delivery caveat. Dense but nearly every clause carries information; the final clause about not waking an idle host is terse and slightly cryptic but still earns its place.

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

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

For a 3-parameter mutating tool with no output schema, the description covers auth, idempotency, recipient resolution, and confidentiality. The notable omission is what a successful call returns (message ID? receipt?) and whether the send is revocable, which an agent deciding how to log or retry would want.

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

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

Schema coverage is only 33% (just 'body'), so the description must carry the other two parameters and largely does: it defines the recipient_actor_id requirement (exact registered actor ID, with pointers to resolvers) and the idempotency_key semantics (idempotent per sender+conversation). Only the key's format/lifetime bound is left to the schema pattern.

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 + scope: 'Send an encrypted direct message to one registered actor.' The verb 'Send' cleanly separates it from the dm_list/dm_read/dm_mark_seen siblings, and 'encrypted' plus 'one registered actor' bounds the surface. It stops short of naming a sibling explicitly, so it is a strong 4 rather than 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?

It routes the agent on how to source the recipient ('an exact registered recipient actor ID from a prior conversation or public_space_get_actor/public_space_list_actors') and states the prerequisite grant (community:dm). That is clear when-to-use context, but there is no explicit when-not-to-use or statement of what to do on failure, so it does not reach 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is partly covered; the description adds the non-obvious trust boundary that reading never installs, executes, or authorizes the skill, plus that referenced text assets are bounded and allowlisted. It stops short of describing the default when revision is omitted or what the response shape looks like, but the output schema covers the latter.

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 locate-then-read workflow, and the second sentence handles the safety boundary and the private-skill alternative. Dense but every clause earns its place; only 'bounded allowlisted referenced text assets' is slightly compressed into jargon.

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?

Read-only, output schema present, and the description covers the workflow prerequisite, the trust boundary, and sibling routing. Remaining gaps are the default revision behavior and what the allowlisted referenced assets concretely are — useful but not blocking for a correct call.

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

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

Schema coverage is 0%, so the description carries the burden: it clarifies that path must be the exact skills/<name>/SKILL.md form (matching the regex) and that revision pins the corpus revision. However, it does not state the revision format (40-hex SHA) or what happens if revision is omitted, leaving real gaps for a two-parameter 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 — read a shared skill's exact skills/<name>/SKILL.md — and names the sibling pair (private_skill_list / private_skill_get) that covers the other case. An agent can distinguish this from community_search and private_skill_get without opening any schema.

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

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

Gives an explicit prerequisite workflow (locate the path with community_search first, then read at that corpus revision) and an explicit exclusion (private user skills go to private_skill_list / private_skill_get). Nothing about when to choose this tool is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context: it clarifies that wallet funds do not increase a Task's ceiling and that the tool cannot mint funds or spend another account's balance, which are important boundaries not captured by annotations.

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

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

The description is three tightly scoped sentences with no filler. It front-loads the primary view option and moves through constraints and the alternative view efficiently, making it easy 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 simple read-only wallet tool with one enum parameter and an output schema, the description covers both views, the default, key limitations, and what information each view returns. The output schema handles return value documentation, so nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single view parameter. It does this well by explaining the meaning of both enum values (summary and activity) and identifying activity as the default, adding meaning beyond the bare 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 resource (Hive Bucks wallet) and distinguishes two views: summary for balances and activity for transactions. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as private_agent_budget or account_usage.

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 explains when to use view=summary versus view=activity, which is useful internal guidance. However, it does not state when to choose this tool over sibling tools or any prerequisites for calling it.

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

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

Annotations already declare read-only, non-destructive and closed-world. The description adds context beyond them: it returns four specific credit categories and requires an ownership plus current selected-Space access check, which is real authorization behavior an agent should anticipate. It does not say what happens when the access check fails.

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

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

One front-loaded sentence that names the returned data first, then the access precondition. Slightly dense phrasing ('after checking its current selected-Space access') but no wasted 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 no explanation, and annotations cover safety. For a single-parameter read tool the description supplies scope, authorization precondition and payload categories; only the task_id format and failure behavior remain unstated.

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

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

Schema description coverage is 0%, so the description must carry task_id meaning. 'An owned internal agent Task' does indicate the identifier refers to a task the caller owns, but nothing conveys the UUID format or that it must be an internal (not community) task.

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

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

States a specific verb and resource: reading four named Credit buckets (accepted, consumed, reserved, available) for an owned internal agent Task. The scope ('owned internal agent Task') implicitly separates it from account_usage and hive_wallet, but it never names those siblings outright.

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

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

Usage is implied by the scope: use this when you need spend details for one internal agent Task. There is no explicit statement of when to prefer account_usage or hive_wallet instead, and no prerequisites (e.g. ownership requirement) spelled out as a selection rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the agents share the selected-Space access model as external agents, which is genuine behavioral context, but it says nothing further about scope of returned data or the rate card's freshness.

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

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

Two compact sentences with the entity list front-loaded, so there is very little waste. Minor slack in the phrasing 'their benefit', which is vague relative to the rest.

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 full annotation coverage, the description only needs to orient the agent, which it does. It omits any mention of when to reach for this versus private_agent_budget, a small gap for a catalog-style 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?

There are zero parameters and 100% schema coverage, so parameter semantics are fully handled by the empty schema. Baseline for a no-param tool is 4.

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

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

The description names the four agent entities (Curator, Private Support, Private Research, Orchestrator) and states the contents are purpose plus current cost rate card, which is concrete and resource-specific. It does not explicitly differentiate from close siblings such as private_agent_budget or private_agent_setup_list, so it falls short of a 5.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance and names no alternatives, though 'Discover ... their purpose and current cost rate card' implies it is the reference step before invoking agent runs. Usage must be inferred from sibling context rather than stated.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value: it discloses the owner-role auth requirement and that revoked grants are returned alongside active ones, which an agent would not know from the annotations 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?

One sentence with no filler, front-loaded with the caller role and the verb. The noun phrase 'registration-bound internal-agent spending grants and their monthly accepted commitments' is dense domain jargon, but each qualifier narrows scope meaningfully.

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, full annotation coverage, and an output schema that documents the return shape, the description covers what remains: caller role, scope of grants returned, and included commitment data. Only the relationship to the budget sibling is left unclear.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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 ('read') and a precisely scoped resource ('active and revoked registration-bound internal-agent spending grants and their monthly accepted commitments'). The read-only framing implicitly separates it from siblings private_agent_delegation_set and private_agent_delegation_revoke, but it never names them or distinguishes itself from private_agent_budget, so differentiation is inferred rather than stated.

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

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

'As the account owner' supplies a useful access precondition, which is a form of usage guidance. However, there is no explicit statement of when to call this versus private_agent_budget or account_usage, and no exclusions or alternatives are offered.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it requires a verified human account owner and explains the practical effect ('cannot admit more paid work or keep using a stale saved 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?

Two tight sentences with no wasted words; the main action and effect are stated clearly. The action verb is slightly delayed by the auth clause, keeping it just short of a 5 for front-loading.

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

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

For a single-parameter, non-open-world mutation with annotations and an output schema, the description covers auth prerequisites and the consequence of revocation. Minor gaps remain around irreversibility and whether the registration record itself is affected, but the essential context is present.

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

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

Schema description coverage is 0%, so the description must carry the burden, but it only implies that the parameter identifies 'one registration'. The schema itself supplies the pattern and length constraint, and the description adds no further semantics about the registration_id format or lookup.

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

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

States a specific verb (revoke) and a precise resource (one registration's internal-agent spending permission), which clearly separates it from the grant-setting sibling. It does not explicitly name sibling tools like private_agent_delegation_set, so it falls short of the 5 bar for explicit 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 phrase 'As the verified human account owner' adds a useful prerequisite, and the consequence sentence implies when revocation is appropriate. However, it never states when to choose this over private_agent_delegation_set or what happens if the grant is already revoked, so usage is only implied.

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 adds real value beyond the annotations: it discloses that this creates no Task and no wallet credit, and that token capabilities and Space membership are separately required. But with destructiveHint=true set, the most important unanswered question is whether setting a grant overwrites or invalidates a prior grant — the description is silent on that, which is the core risk of this mutation.

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

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

Two dense sentences, front-loaded with the authorization condition and ending with the non-effects and dependencies. Nothing is padding, though the phrasing is tightly packed enough that a reader must parse clauses like 'UTC monthly commitment ceiling' carefully.

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 auth plus non-effects are covered. The remaining gap is overwrite/replace semantics for an existing grant, which matters given the destructive hint and is the one thing an agent could get wrong.

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 the semantics, and it does map all three: registration_id ('one claimed registration'), per_task_max_credits ('per-Task maximum'), and monthly_commitment_max_credits ('UTC monthly commitment ceiling'). The UTC qualifier is a useful addition the schema lacks, though the string-typed credit format and units are still 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 states a specific verb (authorize) and a specific resource (one claimed registration's ability to invoke internal agents) with the two spending caps defined. It is clearly distinct from private_agent_delegation_list and private_agent_delegation_revoke, though it never names them 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?

Prerequisites are implied rather than prescribed: the caller must be 'the verified human account owner' and the registration must be 'claimed,' and signed token capabilities plus live Space membership 'remain required.' However, there is no explicit when-to-use guidance versus adjacent tools like private_agent_budget or private_agent_setup_configure, leaving the agent to infer the boundary.

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 say destructive and not read-only; the description goes well beyond by disclosing that broad follows make unreceived history eligible for budgeted catch-up charges, that changing consent fences the old revision and requests Task cancellation, that the caller should inspect cancellation_requested and the retained Task ID, and that discussion text cannot grant spending or disclosure. These are exactly the side effects an agent must weigh before mutating a subscription.

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

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

Five dense sentences, front-loaded with the verb/resource and actor, then escalating to billing and cancellation consequences. Nothing is padded, though the telegraphic phrasing ('Changing consent fences the old revision') trades a little readability for density.

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

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

For a four-variant oneOf schema with a destructive annotation and an output schema, the description covers every action's requirements and the important side effects (chargeable catch-up, cancellation, consent revisioning). Remaining gaps are minor: retry/idempotency expectations and what to do on a revision mismatch are left implicit.

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 high, so structured data already documents most fields; the description still adds meaning by enumerating the four inputs enable requires and by explaining the revision-fencing implication of expected_revision. It does not clarify idempotency_key behavior or how expected_revision conflicts surface, so it stops short of full compensation.

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 four concrete verbs (create, update, enable, disable) bound to a specific resource (an internal agent setup / its Space subscription) and states the actor constraint (account owner). This separates it cleanly from siblings such as private_agent_setup_follow, private_agent_setup_list and private_agent_setup_remove.

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 explicit preconditions for the privileged path ('As the account owner' and the four required enable inputs: rate card, per-Task maximum, aggregate commitment limit, expiry), so an agent knows an enable call is not free-form. It does not, however, route the agent to sibling tools (follow/list/remove) or say when a plain update should be preferred over disable-then-create.

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; the description adds real substance beyond that: broad follows make existing unreceived history eligible (a non-obvious side effect), the action is bounded by subscription limits, and it confers no posting, disclosure or spending authority. It doesn't say whether unfollowing removes already-caught-up history, which is the main remaining behavioral gap.

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

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

Four sentences, front-loaded with the verb and target before the caveats, and each sentence contributes a distinct fact (attention scoping, history catch-up, permission boundary). The 'another chat's acknowledgment does not acknowledge it' line is slightly cryptic but is not padding.

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

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

With annotations covering the safety profile, an output schema covering returns, and a rich schema, the description supplies what structured data cannot: the history-catch-up side effect and the permission ceiling. Only the revision-conflict behavior is left unaddressed, which is a minor gap for a follow/unfollow toggle.

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 reported at 100%, so the schema already carries the parameter structure including the audience const split and target scope variants. The description reinforces the public/private audience dimension and hints that expected_revision must match exactly ('one exact setup revision'), but adds no conflict-handling semantics for a stale revision. Baseline 3 applies.

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

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

States a specific verb pair (follow/unfollow) and a precise resource (a Space, channel or thread bound to one exact setup revision), and the clause 'configures the setup's own attention' implicitly separates it from account-level follow tools like private_space_set_follow. It stops short of naming that sibling explicitly, so the distinction must be inferred.

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 precondition ('as the account owner') and scope ('for one exact setup revision'), which implies when to reach for it, but never states when NOT to use it or which sibling handles the equivalent action for the acting account rather than a setup. The agent has to infer routing from the word 'setup'.

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 data-semantics context (revisions are included; accepted maximum commitments differ from actual charged usage), but that clause is cryptic and doesn't say what permissions are needed or how the two figures relate, so it adds only modest value beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose and no wasted preamble. The trailing commitment/usage sentence is relevant but under-explained, so it slightly undercuts the structure.

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

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

With zero parameters, an output schema, and full read-only annotations, the description needn't explain return shape or safety. What is missing is disambiguation from the crowded private_agent_* family (catalog, budget, configure/follow/remove) and clarity on what 'subscription limits' and 'commitments' actually mean in this listing.

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

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

The tool takes no parameters, so the baseline is 4. The description adds no parameter claims, which is correct, though it also gives no hint about output shape beyond the data semantics.

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

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

The description names the resource precisely (reusable internal agent configurations, revisions, explicitly enabled subscription limits) and frames it as a read operation, so the agent knows what it gets. It does not, however, distinguish itself from close siblings like private_agent_catalog or private_agent_budget, and the second sentence about commitments vs usage sits ambiguously against the budget tool.

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

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

There is no statement of when to call this versus private_agent_catalog, private_agent_budget, or private_agent_setup_configure/remove. The agent must infer the selection criteria from the 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, so the safety bar is lower, yet the description still adds real value beyond them: it discloses the cascade (fences the subscription, requests cancellation of the active Task) and what survives (existing Space knowledge is preserved). What it omits is whether the removal is a hard delete or a soft/archival state, and whether the task cancellation can fail.

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 destructive cascade front-loaded and the preservation guarantee last. 'Fence its subscription' is internal jargon that costs a little clarity but does not pad 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?

An output schema exists, so return values need not be explained, and annotations cover the destructive profile. For a single-parameter destructive tool the description is nearly sufficient, with the only real gap being irreversibility and what happens if the tool is called on a setup with no active Task.

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?

One required setup_id at 0% schema description coverage, so the description must carry the load; it only implies the parameter's meaning via 'one owned saved configuration' and adds nothing about the uuid form or where the id comes from (presumably private_agent_setup_list). Marginal compensation for the coverage gap.

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

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

Specific verb+resource: 'Remove one owned saved configuration', with the ownership qualifier making the scope precise. It doesn't name the sibling families (private_agent_setup_configure / _list / _follow) so the differentiation is implied by the verb 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?

Usage is only implied by the verb and the phrase 'request ordinary cancellation of its active Task', which hints that agent_task_cancel is the standalone alternative but never says so. No when-not-to-use, no warning that this is irreversible, no prerequisite/ownership check guidance.

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

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

Beyond the annotations, the description adds important billing and authorization behavior: the invoker is charged for agent AI and compute, each accessed Space owner pays infrastructure usage, included weekly coverage is consumed before purchased Credits, and membership does not authorize using another account's Credits. The destructiveHint is acknowledged indirectly through write Spaces and retention, but the description does not fully explain what retention='delete' destroys.

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 purpose and key configuration choices, followed by billing and authorization constraints. Four sentences are dense and mostly earn their place, though the retention/destructive aspect could be stated more directly.

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

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

For a 13-parameter, nested, destructive task-launching tool with 0% schema description coverage, the description leaves too much unexplained. It covers cost and permission context well but misses required parameters, mode selection, idempotency, retention semantics, and disclosure behavior, so an agent cannot call it confidently from the description 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 0%, so the description must carry parameter meaning, but it only covers read/write Spaces, retention, accepted_rate_card, and max_credits. It omits required parameters like request and idempotency_key, and gives no guidance on curator modes, timeout_seconds, destination_space_id, cross_space_disclosure, discussion, or public_research_queries.

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

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

The description states a specific verb and resource: 'Start a funded curator Task', and lists the key configuration axes (read/write Spaces, retention, rate card, max Credit budget). It is clear what the tool does, but it does not distinguish it from sibling run tools such as private_orchestrator_run or private_research_run.

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 describing a funded curator Task with exact space selection, but it does not compare it to alternatives or state when not to use it. An agent must infer that this is the right tool only when it specifically needs curator functionality.

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

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

Annotations only cover readOnly/destructive/openWorld, so the description carries real weight: it discloses billing (weekly coverage then purchased Credits), states 'This never launches an agent' (important among the agent_* siblings), and warns that sources/skills are untrusted reference data rather than permission. It does not disclose what the response looks like or whether the write is atomic, but the output schema covers returns.

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 creation action and space default are front-loaded, and each sentence carries distinct information (defaulting, billing, no-agent-launch, versioning, trust model). The sentence 'Updates and removal require the exact current version; skills share this knowledge authority' bundles two unrelated points, which slightly muddies readability.

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

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

For a nested, 8-parameter mutation tool with an output schema and useful annotations, the description covers the non-obvious operational facts well but leaves required inputs like idempotency_key and kind unexplained. An agent could call it, but would be guessing at several required field semantics.

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% across 8 parameters including 4 required ones, so the description must compensate and largely does not. It explains space_id's omission behavior and characterizes sources as untrusted reference data, but says nothing about idempotency_key, title, text, path, the 'kind' enum values, or the provenance/premise_versions structure.

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

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

Opens with a specific verb+resource ('Create entries') and scopes it to one authorized private Space, defaulting to Personal. It implicitly distinguishes itself from private_knowledge_update/remove by noting that updates and removal need the exact current version, but it never names those siblings outright.

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

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

The omission rule for space_id ('Personal when needed') gives usable context, and the note that updates/removal require a current version hints that this tool is for new entries only. There is no explicit when-to-use / when-not / alternative-tool routing against the many sibling knowledge and skill tools.

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

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

Goes well beyond the readOnly/non-destructive annotations: billing semantics (owner charged against weekly coverage then Credits), explicit statement that no agent is launched, and that sources/skills are untrusted reference data. Some of this (version requirements for updates/removal) describes other tools rather than this one, which is noise but does not contradict anything.

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

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

Dense and mostly front-loaded on scope, but several sentences are about adjacent tools (updates/removal versioning, skills sharing authority) rather than this export operation, diluting focus for a read-only 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?

An output schema exists so return values need not be described, but with four undocumented parameters and no explanation of include_history or pagination, the definition is not complete enough for an agent to invoke this confidently.

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

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

Schema description coverage is 0%, so the description carries the full burden. It only hints at space_id ('Personal when omitted'); limit, cursor, and especially include_history are never explained, leaving an agent unable to know what include_history changes or how pagination works.

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 ('Export') and resource ('entries in one currently authorized private Space') with the default scope noted. However, it never distinguishes itself from the closely related private_knowledge_list / private_knowledge_search / private_knowledge_history siblings, so an agent cannot tell why 'export' differs from 'list'.

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

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

One explicit alternative is given: 'use private_space_personal for explicit first-use setup.' That is genuinely useful routing. But there is no guidance on when to pick export over private_knowledge_list/search/history, which are the most likely alternatives for a read of knowledge.

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 meaningful context beyond annotations: reads do not create Personal, billing is charged to the Space owner, this never launches an agent, and skills/sources are untrusted reference data rather than permissions. These are useful behavioral disclosures without contradicting 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 first sentence is properly front-loaded and defines the operation. However, later sentences cover billing mechanics, agent-launch guarantees, update/removal version requirements, and trust-model boilerplate that are tangential to a pure get operation, making the description longer than necessary.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. The description covers authorization context, the Personal default, billing implications, and trust boundaries. The main gap is the unexplained required knowledge_id parameter, which prevents a perfect score.

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 addresses space_id indirectly by saying 'Personal when omitted,' which explains the optional parameter's default. But the required knowledge_id parameter is not explained at all beyond the vague word 'entries,' leaving the most important parameter semantically 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 states a specific verb+resource: 'Get entries in one currently authorized private Space.' It distinguishes scope by naming the default (Personal when omitted) and routes first-use setup to private_space_personal. It does not explicitly distinguish itself from siblings like private_knowledge_list or private_knowledge_search, but the core purpose is clear.

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

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

It gives one explicit alternative ('use private_space_personal for explicit first-use setup') and clarifies that reads do not create Personal. However, it provides no guidance on when to use this tool versus private_knowledge_list, private_knowledge_search, or private_knowledge_history, leaving the main selection decision implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description adds meaningful non-schema behavior: reads do not create Personal, space infrastructure usage is charged to the owner, and this never launches an agent. It also warns that sources and skills are untrusted reference data, which is useful operational context.

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

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

The first sentence is front-loaded and the description is not excessively long, but several sentences mix in adjacent concerns such as update/removal versioning and skill authority that do not directly help an agent invoke this read-only history 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?

Although an output schema and annotations exist, the description still leaves core context unclear: what a 'history entry' is, how knowledge_id selects the item, and how limit/cursor shape the result. It supplies operational caveats but not the basic invocation semantics needed for this specific 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 0%, so the description must carry parameter meaning. It explains that omitting space_id selects Personal, but it does not explain the required knowledge_id, the limit/cursor pagination behavior, or the expected identifier semantics.

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

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

The description identifies 'History entries in one currently authorized private Space' and mentions Personal as the default, but it never uses a specific verb or states that this returns version history for the required knowledge_id. It only partially distinguishes the tool from siblings such as private_knowledge_get, private_knowledge_list, and private_knowledge_search.

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 one explicit alternative and condition: use private_space_personal for explicit first-use setup because reads do not create Personal. However, it does not say when to use this history tool instead of private_knowledge_get/list/search, leaving the main sibling-routing decision implied.

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 readOnly, non-destructive, closed-world behavior, and the description adds meaningful context: reading does not create Personal, billing falls to the Space owner against weekly coverage then purchased Credits, and listing never launches an agent. It also adds security context that sources and skills are untrusted reference data and not permission, which is valuable 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 in the first sentence and the description is not excessively long. Still, several sentences address adjacent concerns such as updates/removal versioning and skills sharing knowledge authority, which are not tightly focused on invoking this list tool.

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

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

The description covers purpose, setup default, billing, and security context, and an output schema exists so return values need not be explained. But with six undocumented parameters at 0% schema coverage, the description is not complete enough to guide filtering or pagination choices without inspecting 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?

Schema description coverage is 0% across six parameters, so the description carries the full burden. It only clarifies that space_id omission defaults to Personal; it says nothing about limit, cursor, path_prefix, inference_status, or premise_knowledge_id, leaving most filtering and pagination semantics 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 states a specific verb and resource: listing entries in one currently authorized private Space, with Personal as the default. It distinguishes the setup case by naming private_space_personal, but does not explicitly contrast with private_knowledge_search or private_knowledge_get, so sibling differentiation is good but not complete.

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 the default behavior when space_id is omitted and explicitly routes first-use setup to private_space_personal, which is useful guidance. However, it does not say when to use this list operation instead of private_knowledge_search or private_knowledge_get, so the main sibling usage conditions are only implied.

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, but the description adds real context beyond them: the exact-current-version requirement, Personal fallback, billing behavior (owner charged against weekly coverage then credits), and the fact it never launches an agent. The security caveat about untrusted reference data is a bonus, though somewhat boilerplate.

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 sentence, but the billing sentence and the 'skills share this knowledge authority / untrusted reference data' remarks read as tangential boilerplate for a removal tool, diluting focus.

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 mutation with an output schema (so return values needn't be explained), it covers versioning, defaulting, and safety semantics adequately. The unexplained idempotency_key and the ambiguous untrusted-data clause leave gaps an agent would still have to guess at.

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

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

Schema description coverage is 0%, so the description must carry the burden, but it only clarifies space_id (Personal when omitted) and expected_version_id (exact current version). knowledge_id and especially idempotency_key receive no explanation, leaving half the parameters opaque.

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 first sentence gives a specific verb (Remove) and resource (entries) scoped to one private Space, which distinguishes it from read/list siblings like private_knowledge_get and private_knowledge_list. It does not explicitly name the update sibling it parallels, but the destructive verb makes the purpose unambiguous.

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

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

It surfaces useful prerequisites — an omitted space_id defaults to Personal, and removal requires the exact current version. However, it never contrasts this with private_knowledge_update or explains when an agent should remove vs. update/export, leaving alternative-routing implicit.

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

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

Beyond the readOnly/destructive annotations, it discloses billing behavior (space infrastructure charged to the owner against weekly coverage, then Credits), that the call never launches an agent, that reads do not create a Personal space, and that sources/skills are untrusted reference data rather than permissions. These are non-obvious side-effect and trust-boundary facts an agent cannot get 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?

It is front-loaded with the scope statement, which is good, but several sentences ('Updates and removal require the exact current version', 'skills share this knowledge authority') describe sibling-tool behavior rather than this read operation and dilute the payload. Dense, but not every sentence earns its place in a search-tool description.

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

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

An output schema exists so return-value explanation is not needed, and the safety/trust profile is well covered. However with zero schema description coverage on 5 parameters, the definition leaves an agent guessing about query construction, pagination and history semantics — a material gap for a search tool.

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

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

Schema coverage is 0% across 5 parameters, and the description only implies what space_id means (defaults to Personal). It says nothing about query syntax or matching semantics, limit bounds, cursor usage, or what include_history changes — the highest-value parameter behavior is 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 first sentence gives a specific verb ('Search'), a specific resource (entries / knowledge) and a scope (one currently authorized private Space, defaulting to Personal). An agent can tell it apart from private_knowledge_get or private_space_full_history_search by scope, though the description 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?

It explicitly routes one case — 'Reads do not create Personal; use private_space_personal for explicit first-use setup' — which is genuine when-to-use guidance. But it never clarifies how this differs from private_knowledge_list, private_knowledge_get, or private_space_full_history_search, so the main selection decision among siblings is left implicit.

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

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

Goes well beyond the annotations: discloses billing behavior (weekly coverage then purchased Credits), that no agent is launched, the optimistic-concurrency requirement that updates/removal need the exact current version, and an explicit prompt-injection caveat that sources/skills are untrusted reference data rather than permission. Some sentences ("skills share this knowledge authority") are cryptic, but the added behavioral context 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?

Front-loaded with the action and scope, and no sentence is pure filler. However, it compresses billing, agent-launch, concurrency, and security notes into terse, jargon-heavy clauses that are hard to parse on first read.

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 mutation with an output schema, it covers the highest-risk unknowns: authorization scope, cost, concurrency/version precondition, and untrusted-data handling. The gap is the undocumented required and nested parameters, which the description leaves entirely to a zero-coverage 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 description coverage is 0% across 10 parameters (including nested sources and provenance), so the description must carry the load. It explains only two of them — space_id defaulting to Personal and expected_version_id needing the exact current version — and says nothing about idempotency_key, kind, path, title, text, sources, or provenance semantics.

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

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

States a specific verb and resource ("Update entries in one currently authorized private Space") plus the default scope (Personal). An agent can distinguish it from create/remove/get siblings by name, though the description never names those alternatives 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?

Useful scope guidance is present — which Space, and the Personal default when space_id is omitted. But there is no routing guidance versus private_knowledge_create, private_knowledge_remove, or private_knowledge_get/history (which the agent needs to obtain expected_version_id), so the when-to-use picture is only implied.

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 destructive/openWorld annotations by disclosing the billing model: the invoker is charged for agent AI and compute, accessed Space owners pay infrastructure usage, included weekly coverage is consumed before purchased Credits, and membership does not confer permission to spend another account's Credits. That is genuinely non-obvious operational context. It stops short of explaining what the destructiveHint actually destroys or what the default 'delete' retention means for the agent's 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?

Three tight sentences with the action and required decisions front-loaded, followed by billing semantics. The final permission sentence is slightly dense but carries real value and there is 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?

The output schema exists, so return values need not be described. However, for a destructive, open-world, 13-parameter tool with nested curator/discussion objects and zero schema descriptions, the description leaves too many invocation-critical decisions unaddressed to be considered 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?

With 0% schema description coverage across 13 parameters, the description must carry the full semantic load, and it only covers read/write Spaces, retention, accepted rate card and max_credits. Curator mode (threads vs supplied), discussion/public_disclosure, cross_space_disclosure, public_research_queries, destination_space_id, idempotency_key and timeout_seconds are left entirely unexplained, which is a substantial gap for a nested 13-parameter 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?

Opening sentence states a specific verb and resource ('Start a funded orchestrator Task'), and 'funded' distinguishes it from the unfunded private_curator_run and private_research_run siblings. It never names those siblings or explicitly states the difference, so the differentiation is implied by an adjective rather than spelled out.

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 when to use it by listing the decisions the caller must make (read/write Spaces, retention, rate card, budget), which gives the agent a pre-flight checklist. But there is no explicit guidance on when to pick orchestrator over curator_run or research_run, and no stated prerequisites such as budget authorization or rate-card acceptance flow.

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 openWorldHint=true and destructiveHint=true, yet the description adds genuinely new behavior: who pays for what (invoker charged for agent AI/compute, Space owners charged infrastructure), that included weekly coverage is consumed before purchased Credits, and a cross-account permission boundary. It does not spell out the destructive consequence implied by destructiveHint (e.g. what retention=delete removes), which keeps it from a 5.

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

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

Purpose is front-loaded in the first sentence and the remaining sentences carry distinct, non-redundant information about billing and permission. The credit-coverage and membership sentences could be tightened, and the parameter expectations are buried in prose rather than enumerated.

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

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

For a 13-parameter, nested-object, cost-incurring, destructive operation, the description covers only a handful of inputs and omits the curator/discussion/disclosure surface entirely. The output schema does relieve it of explaining return values, but the configuration surface an agent must fill in correctly is largely undocumented.

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% across 13 parameters including deeply nested objects, so the description must compensate and largely does not. It names read/write spaces, retention, rate card and max credits, but leaves curator, discussion.*, cross_space_disclosure, destination_space_id, public_research_queries, idempotency_key and timeout_seconds entirely unexplained in both schema and 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?

Opens with a specific verb+resource: "Start a funded research Task." That is clearly distinct from list/read siblings. It never names or contrasts with the very similar private_curator_run, private_orchestrator_run, or private_support_run, so an agent cannot confidently choose among the run-family without opening schemas.

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

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

"Select exact read and write Spaces, retention, the accepted rate card and a maximum Credit budget" implies the setup required before invoking, which is real usage context. But there is no explicit when-to-use/when-not, no mention of prerequisites like the agent setup/delegation siblings, and no routing away from the other *_run tools.

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

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

Annotations already declare this is a non-read, non-destructive, closed-world write, and the description adds real value on top: the owner incurs ordinary Space usage (a billing consequence), and the operation is explicitly scoped to persistence only — no agent launch, curation, publication, or execution. What it omits is the idempotency/retry contract despite an idempotency_key being required.

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

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

Two sentences, zero filler, with the core action front-loaded before the boundary conditions. Every clause carries distinct information.

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

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

The output schema and annotations relieve the description of return-value and safety detail, and the purpose/boundary statements are solid. But for a 6-parameter write with four required fields and a nested provenance structure, silence on idempotency_key and source_refs leaves a meaningful 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?

Top-level schema description coverage is 0%, so the description carries the burden and largely fails: only space_id ('the selected Space') and instructions ('exact SKILL.md') are obliquely implied. The required idempotency_key and the source_refs evidence array (up to 8 items, credential-free URI/excerpt provenance rules) get no mention at all.

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 an exact private SKILL.md in the selected Space' — which an agent can distinguish from private_skill_get/list/update by the verb alone. It does not explicitly name a sibling, but the create-vs-read/update distinction is unambiguous.

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

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

The clause 'this does not launch an agent, curate, publish or execute the skill' usefully rules out a class of mistaken expectations about what creating a skill accomplishes. However, it never routes the agent to the actual alternatives (private_skill_update to modify, private_skill_get to read back, private_skill_list to discover), so when-to-use-vs-sibling is only implied.

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 the safety profile is largely covered. The description still adds real value beyond them: omitting space_id does not create a space, and the returned instructions cannot expand task grants or spending — a security-relevant constraint an agent wouldn't infer from the annotations.

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

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

Two dense sentences with the resource and return content front-loaded, then the space_id fallback, then the safety caveat. Every clause carries information, though the grants/spending sentence is a non-sequitur in placement relative to the read operation.

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 shape needs no explanation, and annotations cover safety. What's missing is the behavior of the uncharted content_sha256 parameter — a read tool with a hash argument implies version pinning or concurrency control that the description never explains.

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 and it only partly does. It explains the space_id omission semantics well and implies knowledge_id identifies the entry, but content_sha256 is only alluded to as 'with its hash' and it is never stated whether it is an input precondition, nor what happens on mismatch.

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

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

States a specific verb and resource: read the exact SKILL.md of a current private knowledge entry, returning it with its hash. That is concrete enough to act on, but it doesn't distinguish this from private_knowledge_get or get_skill, which an agent could easily confuse with it.

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

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

Names an explicit alternative and the condition that selects it: an omitted space_id reads existing Personal without creating it, and private_space_personal exists for explicit first-use setup. It gives no guidance on when to prefer this over private_knowledge_get or get_skill, so the routing is only partly 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 readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is well covered. The description adds a non-obvious disclosure that omitting space_id does not create a Personal space — a real side-effect clarification that annotations cannot express. It stops short of describing pagination progression or result-shape hints.

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 before the conditional and the alternative. Every clause carries distinct information — no restatement of the name or title.

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

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

For a read-only, three-parameter list tool with an output schema and full annotations, this covers purpose, scoping, the space_id edge case, and next-step routing. The only real gap is how paging with cursor/max_results is expected to work.

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, and it does explain the most semantically loaded parameter (space_id omission behavior). However, cursor and max_results are never mentioned, so paging direction and page-size semantics are left entirely to the name and output schema.

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

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

States a specific verb and resource ('Page current reusable private skills') plus a scope constraint ('in one authorized Space'). This is clearly distinguishable from private_skill_get (exact entry), private_skill_create and private_skill_update without opening any schema.

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

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

Gives explicit routing: omitted space_id reads the existing Personal space, private_space_personal is for explicit first-use setup, and private_skill_get should be used to read a specific entry. Both the when-to-use and the two named alternatives with their selecting conditions are present.

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 destructive=true and non-read-only, and the description adds real context: this is a full replace (not a patch), it is guarded by an expected version (optimistic concurrency), and it incurs owner-paid Space entry cost via the Curator path. It stops short of saying what happens on version mismatch or how idempotency_key behaves.

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 tightly packed sentences with the replace semantics front-loaded. The 'same owner-paid Space entry mutation path as Curator' clause is jargon-heavy and slightly opaque, but it does carry cost/convention 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?

An output schema exists so return values needn't be explained, and the description covers the destructive replace and version precondition. However, for an 8-param destructive mutation it omits failure behavior on version mismatch, idempotency semantics, and how required content fields interact with the replace.

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% across 8 parameters, but the description only explains 2 of them (knowledge_id, expected_version_id). The required name, description, instructions, idempotency_key and the nested source_refs array are left entirely to bare schema types, so the description does little to compensate.

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 ('Replace') and resource ('the exact current private skill revision') plus the two identifying inputs. It distinguishes from siblings like private_skill_get/list/create by emphasizing full revision replacement, though it doesn't explicitly name those alternatives.

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?

Implies usage through 'Replace the exact current private skill revision' and the expected_version_id precondition, but never states when to choose update over create, or what to do when you don't have the current version. No exclusions or alternatives are named.

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

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

Annotations only cover the safety triad; the description adds genuinely non-obvious context — that a generic link yields an owner-approval request rather than immediate access, and that the Space owner bears private usage cost so no subscription is required. Still silent on failure modes, idempotency, or what a pending approval looks like.

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, each earning its place: action, parameter rule, then billing/approval caveat. Front-loaded and waste-free.

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 both invocation modes and cost implications. The remaining gap is workflow guidance — whether to preview first or what to do while approval is pending.

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

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

Schema description coverage is 0%, so the description must carry the meaning of both parameters. It does: it explains what each identifier represents and enforces mutual exclusivity, compensating for the bare regex-only schema.

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

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

States a specific verb+resource ('Accept a recipient-bound invitation') and covers the second mode ('request owner approval for a generic link'). The two-mode framing implicitly distinguishes it from private_space_approve_invitation (owner-side) and private_space_preview_invitation, though it never names them.

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

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

Gives a clear selection rule: one of the two parameters, not both, and maps each parameter to its scenario (recipient-bound vs generic link). It stops short of naming alternatives such as preview_invitation or list_invitations, or stating exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates and can destroy state. The description adds a genuinely useful non-obvious constraint ('approval never grants permission to spend the requester's Credits') and clarifies that rejection happens through the same call. It omits what rejection does to the invitation's lifecycle or whether it is reversible.

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

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

Two tightly written sentences with the role precondition front-loaded and the security caveat appended where it belongs. No filler, though the caveat could be folded more crisply.

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 and annotations cover return values and the safety profile, so those gaps are excused. Still missing for a mutating, dual-mode tool are the effect of rejection, the required pending state, and any documentation of the identifier parameters.

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% across 3 required params, so the schema provides only patterns and types. The description implies the meaning of the `approve` boolean via 'approve ... or reject', but says nothing about space_id or invitation_id semantics, leaving half the parameter space to inference from names.

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 (approve/reject) and resource (invitation), with the actor role ('As the Space owner'). It is distinguishable in meaning from private_space_accept_invitation and private_space_invite_member, but it never names those siblings to make the boundary explicit.

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

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

The owner-role precondition is useful implied usage context, and the approve/reject dual path is described. However, it gives no explicit guidance on when to use this versus preview_invitation or accept_invitation, nor what preconditions (pending state) must hold before calling.

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 say this is a non-read-only, non-destructive, closed-world write, so the description's real value is the two extra facts: the create is atomic, and billing falls on the owner while invited members need no subscription. Those are non-obvious side effects an agent cannot get 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?

Two short sentences with the action and its main consequence front-loaded; no filler or restatement of the tool 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?

An output schema exists, so return values need not be explained, and the billing/atomicity behavior is covered. Still missing for a write tool: the required idempotency key's retry semantics and any note on what identifying fields are needed to form the space.

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% and the description names none of the three parameters. It says nothing about title/purpose constraints or, more importantly, what the required idempotency_key means or how retries interact with it, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a private Space') plus the side effect of owner membership being established in the same operation. The 'private' qualifier implicitly separates it from the public_space_* siblings, though it never names them.

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

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

No indication of when to use this versus alternatives such as private_space_personal or private_space_list, and no prerequisites (e.g. whether the caller needs an existing account/actor) are given. The agent must infer context entirely.

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

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

Annotations already state this is a non-destructive, closed-world write, so the description should add operational context. It mentions an authorization precondition, but does not explain idempotency, side effects, or required permissions, and the "shared seen state does not prove receipt" sentence is confusing and seemingly unrelated.

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 first sentence is short and front-loaded with the core action and scope. The second sentence does not earn its place because it discusses reply/mention/seen-state semantics that do not clarify channel creation.

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

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

For a create mutation with four required, undocumented parameters, the definition is not complete: idempotency and parameter meanings are left unexplained. The output schema and annotations cover return/safety concerns, but usage and input semantics remain inadequate.

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 four required parameters. The description only hints that space_id refers to a currently authorized private Space; it says nothing about title, purpose, or idempotency_key, so it does not compensate for the schema 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 names a specific verb and resource ("create channel") and adds scope ("within one currently authorized private Space"), so the basic action is clear. It does not differentiate this from siblings such as private_space_create, and the second sentence is unrelated to channel creation.

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

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

It gives an implied usage context and precondition: the channel must be created within one currently authorized private Space. However, it does not explain when to use this versus alternatives like private_space_create or private_space_list_channels, nor when not to use it.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful scope context the annotations cannot: the token is opaque, it identifies a human account, and it explicitly grants no private Space or DM access. It stops short of disclosing idempotency (does a second call mint a second token?) or revocability, which matters for a credential-like object.

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

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

Two short sentences, zero filler. The positive behavior is stated first and the security caveat second, so the most important qualification is not buried.

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

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

An output schema exists, so return-value details are covered elsewhere, and with no inputs the description carries little remaining burden. The gaps are the credential lifecycle questions (idempotency, revocation, whether the token can be shared repeatedly) and the pointer to resolve_contact_link, which keep it from a 5.

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 (additionalProperties: false), so there is nothing for the description to disambiguate. Baseline 4 applies; the absence of arguments is itself consistent with the 'create a link for yourself' semantics.

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

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

Specific verb+resource: creates an opaque contact token that identifies the caller's human account and the verified actor. That is concrete enough to distinguish it from most siblings. It does not name the paired sibling (private_space_resolve_contact_link), so the create/resolve pairing must be inferred from names alone.

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

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

Usage is only implied: the token exists to be handed out so a counterparty can resolve back to the human account. There is no explicit statement of when to call this versus resolve_contact_link, nor any prerequisite (e.g. actor must be verified/registered) beyond the phrase 'this verified actor'.

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