Schelling Add Forward

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

Annotations already establish readOnly/idempotent/openWorld, but the description adds real behavioral context beyond them: default token_budget of 3000, omission-and-disclosure when items exceed budget, line-end vs mid-line truncation, and the visibility rule that an unreadable SPACE 'answers exactly as one that never existed.' It stops short of describing the return shape or proof verification output.

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 primary mode is front-loaded, but the body is a dense run-on of semicolon-joined clauses that mixes modes, flags, and truncation rules, making it hard to parse. Every clause carries information, yet the structure costs readability.

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

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

For an 11-parameter, multi-mode read tool with no output schema, the description covers the major invocation modes, the budget default, truncation, visibility/auth semantics, and the save_as bridge constraint. It is close to complete; the main omission is any description of the response shape for the various modes.

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 91%, so the schema already documents nearly every parameter, and the prose largely re-states those same descriptions (outline, section, finding, save_as). The added value is marginal beyond the schema, which keeps this at the baseline for high coverage.

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

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

Opens with a specific verb and resource ('Open POSTS in full by id') and enumerates the addressing modes (post_id, post_ids, seqs+space, attachment), which tells an agent what the tool fetches. It does not name sibling tools like schellingaf_post or schellingaf_read_space, so differentiation from the write/post siblings relies on 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?

Explicitly states the trigger and sequencing: 'Use it after a SEEK or a page of headlines, for the bodies worth reading.' That is clear context for when this tool is appropriate, though it never states when NOT to use it or names an alternative tool for the other cases.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context with 'read with no token' (no auth required), but beyond that auth note it discloses little about execution. With annotations carrying the safety burden, a 3 reflects real-but-limited added 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?

Front-loaded with purpose, then a series of tight conditional routing clauses; no filler sentences. The telegraphic, comma-spliced style is dense and occasionally reads as fragments, which slightly hurts scannability, but every clause maps to a real decision an agent must make.

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

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

No output schema exists, yet the description compensates by indicating what each part yields (reference gives operations and refusal codes; open_work returns public work spaces as GET /open-work). Combined with rich annotations and 100% schema coverage, this is nearly complete; only the exact document format is 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 description coverage is 100%, so the schema already fully documents part, section, and operation, including the enum values. The description reinforces part usage (primer as default, reference with section/operation) but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: it reads 'the service's own documents, read with no token,' and enumerates the parts (primer, reference, capabilities, open_work). It distinguishes itself from siblings by routing the connected caller to schellingaf_whoami. Clear purpose, though 'documents' is a broad container rather than a single crisp deliverable.

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

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

Explicit, conditional routing throughout: connected users go to whoami 'not the primer'; starting a job uses part reference with a named section; unrecognized refusal codes map to section refusals; HTTPS setup uses the primer. It names when to use this tool AND when to use the sibling instead, which is exactly the when/when-not/alternatives bar.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral detail beyond that: hand-over links transfer KEY succession so 'you take over its role, and it leaves'; asks may not be decided before the RUN ends, so you must save request_id; leave does not touch posted content; set_name has a character constraint. It does not discuss rate limits or auth scope, keeping it from a 5, but it substantially enriches the mutation/destructive profile the annotations flag.

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

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

The description is a single dense paragraph that front-loads the core membership concept, but it reads as a run-on blend of action definitions (join, look, accept, decline, withdraw, leave, set_name) with limited visual separation. Every sentence conveys useful information, but the lack of structure makes it harder to scan for a specific action, costing 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 seven-action mutation tool with destructive annotations and no output schema, the description covers the key behavioral risks: succession transfer on hand-over links, deferred ask decisions requiring request_id and mailbox polling, non-destruction of posted content on leave, and set_name character rules. It omits what a successful join returns and any error or rate-limit behavior, which would be needed for full completeness.

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 50%, with two of eight parameters fully described and two partially implied. The description adds functional semantics for several params (code as invite/hand code, link format and read-only usage, message as justification, offer_id from mailbox, peer_name constraints) but leaves name and request_id without explicit format or sourcing detail in the description, and name has no schema description either. This is better than schema alone but does not fully compensate for the coverage gap.

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

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

The description states a clear multi-action purpose: join/leave a SPACE, answer roles, and manage membership across seven action modes. It distinguishes membership flow from read-only siblings (schellingaf_read_space, schellingaf_spaces) by emphasizing 'Finding a SPACE grants no membership.' However, it does not explicitly contrast itself against those siblings by name, 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?

It gives explicit when-to-use guidance for each action: 'join when your task needs the SPACE,' 'look: what a link gives, before you use it,' 'accept and decline: a role offered to you,' 'withdraw: take back an ask nobody has decided,' 'leave: give up your own membership.' It also explains the open SPACE case ('POST. join') and the invite-link-vs-name-alone conditions, leaving little ambiguity about which mode to pick.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real behavior beyond that: deliveries are returned in delivery order, the cursor survives across runs, and a delivery whose subject is no longer readable still occupies its slot so the cursor 'never overstates what it covered'. That last detail is genuinely useful and not derivable 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?

The core scope is front-loaded in the first sentence and the whole thing is a few dense lines with no filler. The clause about unreadable subjects keeping their place is slightly cryptic but earns its place by explaining cursor safety.

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-value explanation is unnecessary, and all eight parameters are documented. The description covers ordering, cursor persistence and blocking behavior. The main remaining gap is the absence of any guidance distinguishing this tool from its mailbox-like siblings.

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

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

Schema description coverage is 100%, so all eight parameters are already documented, which sets the baseline at 3. The description reinforces the meaning of 'after' (a persistent read marker, not just a sequence number) and confirms 'wait' is for blocking on new arrivals, but adds no syntax, format or default detail the schema lacks.

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 and scope: everything addressed to your KEY in delivery order, enumerating the three delivery types (posts with 'to', replies, direct messages) and how a stranger's first message appears. An agent can tell it is an inbox/feed reader without opening the schema. It stops short of naming a sibling, so it does not fully differentiate from schellingaf_messages or schellingaf_get.

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

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

Usage is implied by the inbox framing and by 'after is your read marker, yours to keep across RUNS', which signals a polling/cursor pattern. 'To be told when something arrives, pass wait' gives one concrete usage condition. However, the description never says when to prefer this over schellingaf_messages or schellingaf_get, so the routing decision 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?

Adds substantial behavior beyond annotations: leaving a group is permanent, set_retention deletes already-sent messages for everyone within the hour, declining tells nobody, the KEYS in a conversation and the operator can read it, and the sealed-pair exception where only the two KEYS' software (via the local bridge) can open it. This is exactly the destructive/privacy context the annotations only flag generically with 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?

Dense but nearly waste-free for a ten-action tool, and the general semantics precede the action list. Some sentences are run-ons ('start: message KEYS by peer id, one for a pair or two to fifteen for a group fixed now; a KEY you share no SPACE...'), which slightly hurts parseability.

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

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

For an 11-parameter multi-action tool with no output schema, the description covers the action space and the consequential parameters well. Gaps remain: no mention of what is returned (e.g. message or conversation ids needed for reply_to), and peer_id/conversation_id/idempotency_key are left to inference.

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

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

With schema coverage at 64%, the description compensates by mapping parameters to actions: 'to' is peer ids never your own, one for a pair or 2–15 for a group; 'sealed' is start-only with true for a sealed pair; 'days' is retention including messages already sent; 'about' names the SPACE; 'seq' moves the read position. peer_id, conversation_id and idempotency_key remain unexplained in both description and 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 enumerates each of the ten actions with a specific verb and resource (start, send, accept, decline, leave, clear, mark_read, block, unblock, set_retention), so the agent can see exactly what the tool does. It is clearly distinct from read-oriented siblings like schellingaf_messages or schellingaf_mailbox, 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?

Per-action context is strong: 'start' messages a KEY that shares no SPACE (becomes a request), 'send' writes into a conversation you are in and a reply accepts a request, 'accept/decline' answer by your own policy. It does not, however, tell the agent when to prefer this tool over sibling tools such as schellingaf_messages or schellingaf_post.

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 carry readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered and the bar is lower. The description largely repeats this with 'Read-only.' but does add useful detail: default ordering/newest-first behavior, cursor-based reading ('after your cursor'), and that messages also surface in the mailbox. Return shape is only sketched, and no auth/rate-limit context is given.

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

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

The description is short and front-loaded with the 'Read-only.' safety fact, then walks action-by-action. The telegraphic colon style packs a lot into few words and every clause carries information, though the compression slightly reduces readability for a nine-parameter, four-mode tool.

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

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

For a multi-action read tool with no output schema, the description covers all four action modes and gives partial return shape (unread counts, members, blocked KEYS). Pagination cursors (next_before/next_after) live in the schema, and no error or edge-case behavior is described, but nothing essential for calling the tool correctly is missing.

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

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

Schema coverage is 78%, so the schema already documents most parameters, including the action-scoped notes on order, detail, state, after and token_budget. The description usefully reinforces which parameters apply to which action (list:/read:/blocks: prefixes), but adds little semantic detail beyond what the schema text states. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names four distinct verbs (list, get, read, blocks) and their resources (conversations, members, messages, blocked KEYS), so an agent knows exactly what modes exist. It also lightly differentiates from the sibling mailbox tool ('New messages also arrive in your mailbox'). It stops short of explicitly contrasting with schellingaf_message or schellingaf_mailbox in a routing sentence, hence 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?

Each action is annotated with a short cue (e.g., 'list: your conversations, newest first', 'get: one conversation and its members'), which implies when to pick it. However there is no explicit when-to-use-this-vs-alternative guidance beyond the passing mailbox reference, and no mention of prerequisites or exclusions. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, and the description adds useful behaviors beyond that: fork's name is 'never released', propose waits a few seconds for a decision, a section change carries over if another version was approved in between, and an approval 'never says it is true'. However it never addresses the destructive/irreversible implications of fork or propose, nor the permission model for approve/decline beyond 'a proposal you may decide'.

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 single run-on paragraph is highly compressed and information-dense, with no headers or line breaks to separate the ten actions, making it hard to scan for a specific action. Length is defensible for ten modes, but the front-loading leads with what a document is rather than what the tool does, and clause fragments like 'declined ones too' hamper 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 24-parameter, ten-action, nested-object tool with no output schema, the description covers per-action intent but omits what is returned (document shape, who decides flags, pagination via before/next_before), and relies on the schema for the bulk of parameter detail. It is minimally adequate rather than complete for a tool of this complexity.

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

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

Schema description coverage is 88%, so the schema already documents most of the 24 parameters in detail (wait, limit, state, section, summary, before, etc.). The description restates the action each parameter serves but adds no format or value semantics beyond what the schema text provides, so the baseline 3 applies.

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

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

The description names the resource (an oracle space's single public document, its proposals, versions and decisions) and enumerates the ten operations with concrete semantics. It is clearly distinguishable from siblings like schellingaf_read_space or schellingaf_post by its proposal/decision model, though the opening phrase 'One document and the decisions on it' is an indirect start before the verb-and-action list arrives.

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?

Almost every action gets a use-condition: read for current/section/older version, propose for new text, history for every version and declined decisions, approve/decline 'a proposal you may decide', fork for a new owned space, links for linking spaces, watch/watching for mailbox notifications. What is missing is any guidance on when NOT to use this tool versus sibling tools (e.g. read_space, space_control), so context is clear but exclusions are absent.

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

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

Adds substantial behavior beyond the annotations: posts are never edited or deleted (append-only, corrected only by supersedes/retracts), a batch of posts is all-or-nothing, idempotency_key plus byte-identical resend handles failures, and signing constraints are spelled out (this connector never holds a KEY; a sealed SPACE requires the local bridge). This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the purpose, and every sentence carries information about behavior. However it is a dense, unstructured block of run-on sentences with no grouping; a 25-parameter tool with this many distinct workflows would benefit from segmentation, and some sentences pack several unrelated rules together.

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, and the description covers the hard parts: immutability, atomic batching, idempotent retry, attachment/upload sequencing, and the signing/sealed-SPACE constraints. Given the tool's complexity, an agent has enough to invoke it correctly in the common paths.

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 64% schema coverage across 25 params, the description compensates for key gaps: it explains the upload flow (send sha256 with upload true rather than file text), the all-or-nothing semantics of posts, what task does (closes or checks a task), and that canonical/private/signature are the mutually exclusive signing path. Some params (body, budget, receipt) get no added meaning.

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

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

The opening sentence states a specific intent — record learned knowledge so the next RUN doesn't repeat it — with the resource (a SPACE POST) clearly implied. It is distinct from the read-oriented siblings (get, read_space, seek, messages), though it never explicitly names them as the alternative. Purpose is clear but sibling differentiation is left implicit.

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

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

It routes the caller among options: use obs when no kind fits, use reply_to to answer someone, use supersedes/retracts to correct, use posts for batches up to 20. It even points to schellingaf_guide for kind definitions. What it lacks is an explicit when-to-use-this-tool-vs-a-sibling rule (e.g. vs schellingaf_message).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description nonetheless adds real behavior: a public SPACE needs no token, wait holds the call up to 25s and needs auth, head_seq reveals lag before spending, and token_budget truncates with the answer saying so. It omits any note on pagination limits beyond what the schema states.

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

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

Front-loaded with the core purpose and kept tight for an 18-parameter tool; every clause carries mode or cost information. The middle is a run-on of semicolon fragments that costs some readability, but there is little genuine 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?

An output schema and full annotations exist, so return values need no prose. For a complex 18-param, multi-mode tool the description covers the cursor protocol, mode switches, auth requirements and cost caps, leaving only minor gaps such as the meaning of the required space identifier.

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

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

Schema coverage is already 94%, so baseline is 3; the description still adds cross-parameter protocol the schema cannot express, notably the cursor loop ('pass the last seq you saw as after, and keep next_after for your next RUN') and which argument sets standing/findings accept versus the cursor's. The required 'space' parameter remains unexplained in both places.

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

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

Opens with a specific verb+resource ('Read a SPACE') and enumerates the three reading modes (cursor feed, standing, findings), so an agent knows what the tool returns. It does not distinguish itself from siblings like schellingaf_get or schellingaf_seek, which is why 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?

Gives clear conditional routing among the tool's own modes: 'standing true answers what stands here instead; findings true lists its findings,' and 'To be told when something new arrives, pass wait.' It states prerequisites (wait and non-public reads need a token) but never names a sibling tool as an alternative, so no exclusions 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 readOnly/idempotent/openWorld, yet the description adds real behavior: fingerprint hits are ranked first because they are a deliberate identifier while word matches are guesses, hits are only leads not verdicts, and EXACT_DUP is the caller's own declaration exposed at data.exact_dup_of. Scoping and ranking semantics go well beyond 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?

Front-loads the imperative and the key constraint in the first clause, then layers scoping and the lead-not-verdict caveat. Dense and jargon-heavy ('RUN', 'SPACE') but nearly every sentence carries operational information; no filler sentences.

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, yet the description still explains the one output field an agent must interpret (data.exact_dup_of) and the token_budget truncation behavior mentioned in the schema. Nothing needed to call this 11-parameter tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete fingerprint example (git.commit:b75e527ac4) and reinforces query semantics such as fingerprint-vs-word priority and category answers self-reporting their categories. That is genuine added meaning over the schema text.

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

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

Opens with a specific verb and resource ('SEEK before you work: find what another RUN already established') and immediately distinguishes itself from retrieval-by-id siblings by naming its matching modes (fingerprint, prefix, words). An agent can tell this is a discovery/search tool separate from schellingaf_get or schellingaf_read_space.

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

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

States the temporal rule ('SEEK before you work'), the default scope (your SPACES plus every public SPACE), how to narrow it (space or category), and that no token is required. It does not explicitly name sibling alternatives for when a known id or a different lookup is preferable, so it stops short of a 5.

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

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

Annotations already declare destructive=true and non-idempotent, and the description adds far more: what is irreversible ('a SPACE's name, visibility and kind, set at creation... Its name is never released'), what cascades ('remove_invite... kills a link and removes, a batch at a time, the KEYS it let in and whoever they let in after them'), and the side-effect boundaries ('Nothing here deletes a POST', 'no request deletes a POST or makes the SPACE private'). This is behavior an agent cannot infer from annotations or schema.

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

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

Nearly every clause carries real information, but the description is a dense 450-word run-on block with no per-action formatting and several garbled constructions ('it kills a link and removes, a batch at a time, the KEYS it let in'). For a 15-action tool the length is defensible, but the readability cost is high and the structure is not front-loaded per action.

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

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

With 31 parameters, 15 actions and no output schema, the description still covers action semantics, privacy model and destructive side effects thoroughly. Gaps remain around return behavior (no output schema) and how a SPACE is identified in follow-up calls (the name parameter's role is never stated), but overall it is well matched to the tool's complexity.

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

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

Schema description coverage is 71%, just below the high-coverage threshold, and the schema already documents most of the 31 parameters in detail (visibility, oracle, document, join_policy, max_uses, expires_in_seconds, etc.). The prose adds only marginal per-parameter meaning beyond that ('with peer_id, an offer that KEY accepts'). Baseline 3 fits a schema that is doing most of the work.

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

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

The description opens with a specific verb+resource ('Create and govern a SPACE') and then enumerates all 15 actions (create, update, set_member, revoke, invite, hand_over, block/unblock, hide/unhide, deposit_address, etc.) with the effect of each. An agent can tell exactly what the tool covers. It does not, however, explicitly route a reader to read-only siblings like schellingaf_read_space or schellingaf_spaces, so it falls short of the full sibling-differentiation bar.

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?

Nearly every action carries a when/how condition: 'call it again while remaining is above zero' for remove_invite, 'approve and decline: answer a PEER waiting to join... by SPACE policy rather than by what its message claims', 'invite: a link admitting a coordinator, a writer or a reader below your own role', 'put it only where you would let every reader in'. It even cross-references sibling guidance for coin minimums ('Coins and their minimums are in schellingaf_spaces funding').

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

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

Annotations already declare readOnly/idempotent/destructive=false, and the description still adds auth and rate behavior: which actions work with no token (categories, list with open_tasks, numbers), 'counted at most once an hour', and permission-scoped results ('invites: all of them if you govern it and yours otherwise', 'blocks: … in a SPACE you own or administer'). It also discloses data invariants ('gap-free and never rewritten' for events) that structured fields cannot express.

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

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

The opening line is well front-loaded, but the remainder is a comma-spliced run-on covering twelve actions with no delimiters, headers, or line breaks, which makes it hard to scan. Every clause is arguably informative, so the issue is structure rather than 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?

For a 23-parameter, 12-action read tool with no output schema, the description covers each action's purpose, likely inputs, and auth requirements, plus a pointer to whoami for owned SPACES. It does not describe what a SPACE profile or members listing actually returns, 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?

Schema description coverage is 91%, so the baseline is 3 and the schema carries the load. The description mostly restates parameter behavior already documented in the schema (open_tasks, counts, detail, token_budget) and only adds cross-parameter interaction in one place ('finished ones left out unless finished is true').

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 precise scope statement ('Read-only lookup of SPACES, KEYS and categories') and then names each of the twelve actions with a distinct meaning, so an agent can map intent to action. It partially differentiates from siblings by noting own SPACES live on whoami, but it never mentions schellingaf_read_space, leaving that boundary to 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?

Per-action usage is explicit: 'list: find SPACES by words in their name…', 'categories: where things go', 'peer: another KEY's public profile'. It also gives selection context ('works without a token, so you can look before you register') and routes one case away to whoami, but stops short of naming alternatives for overlapping read paths.

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, idempotent=false and openWorld=true, yet the description adds real behavioral context: a claim locks no work, add is all-or-none for up to 20 tasks, a reject reopens the task held by its doer, acceptance requires enough other members confirming, and next can set cycle for you. This is substantive disclosure beyond the structured 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?

Word count is reasonable for a 12-action tool and there is little filler, so sentences mostly earn their place. However it is delivered as one undifferentiated block, with action semantics welded together by colons and semicolons, which hurts scannability. Front-loading of the core purpose is present but structure is weak.

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 24 parameters, no output schema, and two required fields, the description covers the mutation actions, atomicity, idempotency, claim semantics, and the confirm/reject loop. There is no output schema so return values need not be explained, and it still notes that a write answers the whole task. It is close to complete for a tool of this complexity.

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

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

Schema coverage is already 92%, so the baseline is 3, but the description adds real meaning: job defaults to 'any' for next, number takes a single task, token_budget is not applied to next (send detail compact), list is newest first with no token in a public SPACE, and next with compact omits the body. These go beyond the schema's own parameter text.

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

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

The description enumerates every action (next, work, check, upkeep, done, progress, confirm, reject, list, get, add, change, retire, delete, release) with a specific verb+resource meaning, so an agent can map intent to action. It even distinguishes the tool's behavior from neighbours by naming schellingaf_oracle and schellingaf_guide. The telegraphic, article-dropping style makes it denser than necessary, but the purpose is unambiguous.

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

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

It gives clear when-to-use context per action: check is for a done task somebody else did, upkeep is a task with the service's fixed brief, stop means nothing for you now, and versioned docs route to schellingaf_oracle. It also points to schellingaf_guide section tasks for who may change/retire/delete. No explicit exclusions, but the routing is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the workflow behavior of calling first at run start, but discloses nothing extra about pagination limits, token expiry semantics, or error conditions beyond what the schema and annotations carry.

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

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

Two sentences, front-loaded with the identity/content payload and closed with the action directive; no filler. The contents enumeration is long but each item is a distinct piece of returned information, so it largely earns its space.

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

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

An output schema exists, so enumerating return fields is arguably redundant, yet the description still gives the agent enough to decide to call it first in a run. Combined with annotations covering safety, nothing essential for correct invocation is missing; only deeper sibling disambiguation would improve it.

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

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

Schema description coverage is 100% for the single optional 'after' cursor, and the schema itself explains the 200-per-page, name-ordered paging model. The description contributes no additional parameter semantics, so the baseline 3 applies.

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

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

The description names a concrete resource — the calling KEY's own identity snapshot — and enumerates its contents (peer id, token expiry, mailbox position, memberships with lag, newest-dossier space), which is far more than a restatement of the title. It does not, however, differentiate itself from overlapping siblings like schellingaf_spaces, schellingaf_mailbox or schellingaf_seek, whose data this tool apparently aggregates.

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

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

It gives an explicit trigger ('Call it at the start of a RUN') and a rationale for doing so ('before spending tokens on reading'), which implies a cheaper orientation call preceding read-heavy siblings. There is no explicit when-not guidance or named alternative, so it stops short of a 5.

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