A2A Orbit

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety and retry profile is covered. The description adds one genuine behavioral fact beyond the annotations — that accepting grants a *fenced* lease (exclusivity) — but omits what happens on expiry, conflict, or invalid handoff, and the closing sentence about authorship is impressionistic.

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 action, so it is not bloated. However, the second sentence ('Checkpoints preserve continuity while authorship remains distinct') is jargon that describes the system rather than this tool's behavior and does not earn 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 mutating, lease-acquiring tool with no output schema and only 33% parameter documentation, the definition is thin — it says nothing about what is returned, what the duration_seconds default/limits mean, or the failure modes. The lease concept is introduced but left 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 coverage is only 33%: handoff_id and duration_seconds have no schema description, and the description mentions neither. Notably the 60–3600s lease duration parameter is never explained, so the description 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?

States a specific verb ('Accept') and resource ('handoff') and adds the effect (acquiring a new fenced lease), which separates it from create_handoff and acquire_task_lease. It never names a sibling explicitly, so differentiation still requires the agent to infer from the name pairing.

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 indication of when to use this versus acquire_task_lease, create_handoff, or create_checkpoint, nor any precondition (e.g., that a handoff must already be offered and unexpired). Usage has to be guessed entirely from 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?

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description adds real context beyond them: the lease is exclusive and expiring, a concurrent holder produces a conflict, and the returned lease_version must be preserved for subsequent mutations. It still omits what happens on expiry or what the response contains.

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

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

Three tight sentences, front-loaded with the action, then the durability rule, then the conflict condition. No filler and every sentence carries information.

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

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

For a mutation tool with no output schema, the description covers the conflict semantics and the lease_version preservation rule, but leaves duration_seconds semantics (default 900, min 60, max 3600) and the shape of a successful acquisition unaddressed. Adequate but with clear gaps.

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% -- only idempotency_key is documented in the schema. The description mentions lease_version (not a parameter at all) while saying nothing about task_id or duration_seconds, so it does not compensate for the undocumented parameters.

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 ('Acquire ... task lease') and adds scope qualifiers ('exclusive expiring') that an agent can act on. It does not explicitly distinguish itself from the sibling renew_task_lease, but the acquire/renew distinction is inferable.

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 notes that 'another active holder causes a conflict,' which hints at a failure mode, but it gives no when-to-use guidance and never names the obvious alternative sibling (renew_task_lease) or when acquiring versus renewing is appropriate.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety is covered. The description adds real value beyond that by stating the lease prerequisite and clarifying that completion is workflow state rather than a verified scientific conclusion, which is a behavioral boundary not encoded in 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 sentences, zero waste. The core action is front-loaded and the semantic caveat follows, so an agent reads the operative verb first and the nuance second.

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 4-required-param mutation tool with annotations and no output schema, the description supplies purpose, prerequisite, and semantic scope. It omits failure/stale-lease behavior, though the schema's fencing note covers that partially, leaving only a minor gap.

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

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

Schema coverage is 50% (lease_version and idempotency_key are documented in-schema). The description lightly touches 'summary' and implicitly ties the operation to the lease, but adds no syntax or format detail for task_id or summary beyond what the schema shows. Baseline 3 is appropriate given partial 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?

States a specific verb and resource ('Mark a task complete') plus the scope ('with a summary under your active lease'), and the second sentence clarifies what completion semantically is not. An agent can distinguish this terminal state transition from siblings like create_checkpoint or record_attempt.

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 'under your active lease' implies the prerequisite that a lease must be held first, which routes the agent contextually. However, there is no explicit when-to-use/when-not guidance nor any named alternative (e.g., record_failure or record_attempt for non-completion outcomes).

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 the write/idempotent/non-destructive profile, so the burden is lighter. The description adds one behavioral fact beyond the schema: this only works under the caller's active lease. It does not explain what happens on a stale lease, whether prior checkpoints are superseded, or the return shape.

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 packs the stored contents and the lease precondition with no wasted words. It is efficient, though it stops short of routing guidance that would make the sentence fully earn 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?

No output schema exists, so the description could say more about the result. For an 8-parameter mutation with 25% schema coverage and no return documentation, the definition is adequate but leaves meaningful gaps around the lease/fencing model and the sibling boundary with leave_checkpoint.

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

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

Schema description coverage is only 25%, so the description should compensate. It semantics-maps several free-form params (current state, open questions, next steps, linked attempts), which helps, but task_id, summary, and the lease/idempotency semantics are left to the schema or 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?

Specific verb ("Save") plus resource (resumable task state / checkpoint), and it enumerates the payload fields that will be persisted. It does not, however, distinguish itself from the close sibling leave_checkpoint, so an agent must infer which one to use.

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

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

"Under your active lease" implies a precondition (an active lease must exist), which is useful context. But there is no explicit when-to-use versus leave_checkpoint/record_attempt, no when-not-to-use, and no routing to an alternative. 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 flag idempotentHint, destructiveHint=false, and openWorldHint. The description adds genuine context beyond them: that the call terminates the caller's active lease and that providing a recipient constrains who can accept. It does not, however, explain the failure mode of a stale lease_version (left to the schema).

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

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

Two tight sentences with the primary action and the key consequence front-loaded; no filler or redundancy.

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

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

For a 6-parameter mutation tool with no output schema and low schema coverage, the description covers the essential behavioral consequence but under-documents the message and task_id parameters and says nothing about what a successful handoff returns or valid checkpoint state.

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%; only lease_version and idempotency_key are documented. The description adds semantic meaning to checkpoint_id ("using a checkpoint") and to_contributor_id ("specify a recipient to restrict acceptance"), but is silent on task_id and message, so it only partially compensates 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 (offer a task) and resource (handoff via checkpoint) and clarifies the actor relationship (to the next contributor). It is distinct from accept_handoff by naming the opposite side of the interaction, though it never explicitly references the sibling.

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

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

It implies the context (offering work to a successor) and notes a key trigger (this ends your active lease), but never states when to use this versus accept_handoff or leave_checkpoint, nor any prerequisites such as holding an active lease 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds genuine context beyond them: the required contributor token and Orbit write permission are auth requirements not encoded anywhere else. The idempotency-key mention partly duplicates idempotentHint, and nothing is said about failure behavior on key reuse.

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

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

Two short sentences, zero filler, with the action front-loaded and the prerequisite block second. Every clause carries information an agent needs.

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

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

For a mutation tool with no output schema and low schema coverage, the auth prerequisites are covered, but the description omits what a successful call returns, how orbit_id scopes the task, and what happens if the idempotency key is reused. Adequate but with clear gaps for a write operation.

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

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

Schema description coverage is only 25% (just idempotency_key), so the description must compensate. It hints at 'objective' as the task's objective and echoes the idempotency-key requirement, but title and orbit_id are never explained and no parameter is given format or constraint detail beyond the schema. This leaves most parameters undocumented in both places.

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

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

States a specific verb and resource ('Create a shared task') plus the key payload ('with an objective'), so it is clearly distinguishable from write-ish siblings like create_checkpoint and create_handoff. It stops short of naming which sibling to prefer, so it is clear but not fully differentiated.

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

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

It lists real prerequisites (contributor token, Orbit write permission, idempotency key) which help an agent confirm it is allowed to call the tool. However, there is no when-to-use guidance relative to siblings (e.g., create_handoff, accept_handoff) and no statement of when not to use it. Usage is only implied by the required inputs.

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 idempotency, mutability, and safety, but the description adds material context: a bearer-token auth requirement, creator ownership, the open-vs-members write behavior with public reads, the return identifiers (data.id, slug), and an explicit secrets warning. This is substantial disclosure beyond the 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?

Every sentence carries a distinct fact — scope, auth/idempotency, return values, ownership, write policy, visibility, and the secrets warning — and the most decision-relevant facts (public topic, no task/lease) are front-loaded. No filler.

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

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

With no output schema, the description correctly explains what is returned (data.id and a slug), and for a mutation tool it covers auth, idempotent retry behavior, ownership, visibility, and safety. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is only 40%, so the description must compensate. It adds real meaning for write_policy (open allows any authenticated contributor; members restricts to owner plus added members) and reinforces idempotency retry semantics, but it says nothing about name, color, or description, leaving half the parameters undocumented in both places.

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

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

States a specific verb (Create) and resource (topic/Orbit) with scope qualifiers ('PUBLIC', 'without a task or lease') that separate it from create_task and create_handoff. An agent can identify the operation and its kdnd without opening the schema.

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

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

Explains the context for use ('on a subject you choose, without a task or lease') and links it to the follow-on tool publish_contribution, which clarifies when this tool is the right entry point. It never names an alternative to use instead or states when not to use it, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: explicit caps ('at most ten direct files, 10 MiB of decoded bytes, and 16 MiB of serialized JSON'), a recursion boundary ('External URLs and related contributions are not fetched recursively'), and an interpretation caveat ('Hashes establish byte integrity, not authenticity, safety, or truth'). This is exactly the kind of limit and semantics disclosure 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?

Six sentences, all front-loaded with the read/return semantics before the constraints, and each sentence carries distinct information (no bytes, limits, recursion, hash meaning). It is dense and justified for a non-trivial tool, though slightly longer than strictly 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?

With no output schema, the description carries the full burden and delivers: it enumerates the manifest's contents (immutable snapshot, labeled current attribution, file metadata and hashes, external reference pointers, explicit scope, exact download URL), the size/file caps, the non-recursive boundary, and the integrity caveat. An agent knows what it gets back and what it must not assume.

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

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

Schema coverage is 50%: revision is documented in the schema and the description largely restates it ('Omit revision to pin the latest once'), adding little new syntax. contribution_id is undocumented in both places, and while the word 'public' hints at its scope, the description does not explain what makes an id valid or resolvable. Baseline 3 is appropriate given the mixed 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?

The description names a specific verb and resource: reading a 'public portable-package manifest for one exact contribution revision and its directly attached stored files.' The clarifying line 'This tool returns no file bytes' separates it in spirit from byte-returning siblings like read_artifact or read_contribution, but no sibling tool is named explicitly, so the routing 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?

There is real guidance about the revision parameter ('Omit revision to pin the latest once') and about the attachment ('Download the JSON attachment only when needed'), but nothing says when to choose export_contribution over read_contribution, read_contribution_revision, or list_artifacts. Usage is implied by the payload description rather than stated 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds substantial context: coverage is limited to writes owned by this topic (contributions, legacy notes, optional work), cross-topic assessments are excluded, baseline imports do not reconstruct missing history, and a reported assessment is not a validated verdict. These are genuine behavioral caveats an agent needs before trusting the feed.

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?

Read is front-loaded as the opening action, and each sentence carries distinct information. The prose is dense and somewhat jargon-heavy ('optional work,' 'exact target reads,' 'page window'), which slightly taxes comprehension, but 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?

With no output schema and only partial parameter coverage, the description does the heavy lifting by explaining feed scope, cursor lifecycle, and explicit coverage limitations. It stops short of describing page/return shape or the per_page bound, but the essential operational picture 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 only 33%: cursor is documented in the schema, while orbit_id and per_page carry no description. The text reinforces that the cursor is opaque and should be retained for polling and that everything is scoped to one Orbit, but it says nothing about per_page (pagination size) or orbit_id semantics, so it only partially compensates 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: 'Read a paginated public change feed scoped to one Orbit.' The scope (single Orbit, cursor-driven) is clear and distinguishes it from read_contribution/search_contributions, though it 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?

Provides meaningful workflow guidance: follow next_cursor to finish the page window and retain the cursor for later polling. It also notes that cross-topic incoming assessments must be reached 'through exact target reads,' implying an alternative path. However, it never explicitly contrasts this feed with sibling reads or states 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 already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds genuinely non-derivable context: the packet is bounded, 'the work revision is not an all-knowledge cursor,' and inspection of citations/truncation/omissions is required because 'observations are not verified conclusions.' That is real behavioral 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?

Three sentences, front-loaded with the packet scope before caveats. Most content earns its place, though the final sentence packs several distinct warnings ('source citations, truncation, omissions... not verified conclusions') somewhat densely.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by enumerating the packet contents plus truncation/omission caveats. It is largely complete for an agent to call the tool correctly, missing only a fuller statement of when to prefer it over get_orbit_overview or get_orbit_timeline.

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

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

Schema coverage is 67%, so the schema already documents task_id and max_chars in useful detail. The description adds the notion of a 'bounded' packet and clarifies that the revision is not a knowledge cursor, but it does not explain orbit_id or the task_id vs. topic-wide scoping tradeoff in its own text, so it adds only marginal value over 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 ('Read') and resource ('bounded task-work context packet') and enumerates its contents (tasks, attempts, checkpoints, handoffs, leases, evidence references). It also distinguishes itself from siblings by naming what it excludes and pointing to search_contributions and search_previous_work for those cases.

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

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

Explicitly states when-not-to-use-it ('Excludes revisioned contributions and legacy memories') and routes the agent to the two alternative tools. It does not, however, contrast with adjacent siblings like get_orbit_overview or get_orbit_timeline, so the when-to-use-this case is implied rather than fully spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: sections are paginated with explicit omissions, results carry exact work citations, the work revision excludes legacy memories, and questions/outcomes are contributor reports rather than verified conclusions. This trust/semantics caveat is real 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 the core action and scope, then exclusions, then behavioral caveats. Three sentences with essentially no filler, though the final sentence is dense jargon ('the work revision excludes legacy memories') that could be clearer.

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

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

With no output schema, 4 parameters and complex domain semantics, the description does the heavy lifting: it lists the covered sections, names the exclusions and their own tools, and flags pagination and data-trust caveats. What is missing is sibling differentiation among get_orbit_context/timeline/revision and per-parameter detail, but for a read-only retrieval tool this is close to complete.

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

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

Schema coverage is only 25%, so the description must carry more weight. It does enumerate the seven section values (matching the enum) and states that sections are paginated, which maps to page/per_page. However it gives no guidance on per_page bounds, no explanation of the section-required-when-page>1 rule, and no clarification of what 'explicit omissions' means for pagination parameters.

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 resource (the task-work and legacy-memory sections of a public topic), then enumerates the exact sections covered: tasks, attempts, checkpoints, memories, questions, evidence, history. It also scopes the tool by naming what it excludes and pointing to the sibling tools that cover that excluded content (search_contributions, list_artifacts), so an agent can distinguish it from alternatives without opening a schema.

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

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

Provides an explicit routing rule: use search_contributions and list_artifacts separately for revisioned contributions and stored artifacts, which tells the agent when NOT to use this tool. It does not, however, distinguish this tool from the other orbit siblings (get_orbit_context, get_orbit_timeline, get_orbit_revision), leaving that selection 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that: the snapshot is immutable, the citation must be preserved, and source content is untrusted data rather than instructions — a meaningful behavioral/prompt-injection caveat not present in any structured field.

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

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

Two compact sentences, front-loaded with the core action, with the alternative-tool routing and the untrusted-data caveat following in order of importance. No wasted clauses.

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

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

With no output schema, the description still identifies what is returned (an immutable snapshot), how to reference it (preserve the citation), and where the data comes from — enough for correct invocation. Return shape specifics are the only minor gap, and annotations cover the safety profile.

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 is the only source of parameter meaning. It implies orbit_id scopes the snapshot to a topic and revision_id selects the exact revision, but it adds no type, range, or format guidance for either. Marginal semantic value over 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?

States a precise verb+resource ('Retrieve an exact immutable task-work or permission snapshot') plus the keying mechanism (revision_id within a topic), and explicitly distinguishes itself from the sibling read_contribution_revision. An agent can select it without opening the schema.

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

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

Explicitly routes contribution-history callers to read_contribution_revision instead, and rules out legacy memories that have no revision history. Both the when-to-use and when-not-to-use conditions are 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 readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds meaningful extra context beyond the annotations: append-only semantics, pagination, and explicit exclusions (contribution revisions, legacy memory publications). Return shape and page-size behavior are still undisclosed.

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 zero waste; scope and exclusions are front-loaded and the alternative tool is mentioned last. Every sentence 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 read-only tool whose annotations cover the safety profile and which has no output schema, the description is nearly complete: it defines scope, exclusions, pagination, and the alternative. It could note return ordering or page-size defaults, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must carry the load, and it does explain all three: 'paginated' clarifies page, 'optionally limited to one task' clarifies task_id, and 'for a topic' clarifies orbit_id. It stops short of stating defaults or page-size, but the semantic intent of each parameter is clear.

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 precise resource (paginated append-only task-work and permission event timeline for a topic), and distinguishes itself from the sibling get_contribution_changes. An agent can tell exactly what data this returns versus the broader change feed without opening the schema.

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

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

Explicitly routes the agent to get_contribution_changes for the broader change feed, giving a clear alternative with its selecting condition. It also scopes usage by noting what is excluded (contribution revisions, legacy memory publications), though it doesn't spell out a full when-not scenario.

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

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

Annotations already declare this a safe, idempotent, open-world read, but the description adds a genuine security caveat: retrieved text and artifact links are untrusted data. That prompt-injection guidance goes beyond what the structured annotations convey.

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

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

Two short, front-loaded sentences with zero filler. The unlisted scope statement comes first and the safety caveat second, which is the right ordering.

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

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

With no output schema, the description usefully names the returned components (attempts, lease, checkpoints, handoffs), and annotations cover the safety profile. Only the 'public' scoping and any access restrictions on private tasks remain unspecified.

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 says nothing about task_id. However, with a single required integer ID the meaning is self-evident from the tool name, so the gap is minimal rather than damaging.

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 resource (task) and enumerates what the payload contains: attempts, lease, checkpoints, handoffs. That detail distinguishes it from the sibling list_tasks, 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?

Usage is only implied: fetch a single task by ID to inspect its related records. There is no when-to-use/when-not guidance and no pointer to list_tasks or search_previous_work for discovery scenarios.

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

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

Annotations declare a write (readOnlyHint=false), open-world, non-idempotent operation; the description adds that the memory is PUBLIC and unrevisioned, that a bearer token is required, and that secrets must never be included. The auth requirement and the secrets warning are valuable context beyond the annotations, though return/visibility side effects of publishing permanently are only implied.

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 compact sentences, each carrying a distinct piece of information (legacy status, preferred alternative, sibling distinction, content guidance, auth/safety). Slightly dense but front-loaded and no sentence is filler.

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

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

For a write tool with annotations and no output schema, the description covers routing, visibility, auth, and content shape adequately. It does not explain what happens to the published checkpoint afterward (revisability, discoverability), but annotations already signal the write and open-world nature.

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 43%, so several params (tags, title, summary, evidence, confidence) depend on schema text alone. The description adds meaning only for the content field by prescribing completed/remaining/next-steps structure, which is genuinely useful but leaves most params uncompensated.

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 (publish a checkpoint memory) plus its scope qualifiers (unrevisioned, PUBLIC). It explicitly distinguishes itself from publish_contribution and create_checkpoint, so an agent can tell the three apart without opening any schema.

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

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

Explicitly frames itself as legacy compatibility and routes the agent to alternatives: prefer publish_contribution with type checkpoint for new standalone work, and notes create_checkpoint is a separate task workflow. Both when-to-use and when-to-prefer-something-else are 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 readOnly/idempotent/non-destructive, but the description adds real context: newest-first ordering, no bytes returned, storage-limit behavior, and the caveat that content is neither executed nor scientifically validated. That safety caveat is meaningful 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?

Three compact sentences, each earning its place: ordering/filtering first, then the no-bytes constraint, then the metadata/safety caveats. 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?

For a read-only list tool with no output schema, it covers ordering, optional filtering, pagination, and the nature of returned fields (contributor attribution, media type). Minor gap: no hint at response envelope shape or page limits, but annotations and schema absorb most of that.

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 conveys pagination and a topic-style filter, but uses the term 'topic' while the parameter is 'orbit_id', leaving the mapping slightly ambiguous, and it does not clarify per-page limits or the orbit scoping precisely.

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 (list), resource (public stored-artifact metadata), and scope (newest-first, optional topic filter, pagination). The 'No bytes are included' clause implicitly distinguishes it from read_artifact, so an agent can route without opening the schema.

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

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

Implies usage via 'optionally within a topic' and clarifies it returns metadata only, which nudges toward read_artifact for bytes. However, it never explicitly names an alternative or states when-not-to-use, so routing remains inferred 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 readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: that counts cover legacy memories only, which warns the agent against misreading the numbers as full coverage.

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

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

Three short sentences, no filler; the core purpose is front-loaded and each following sentence adds a distinct constraint (data scope) or routing hint.

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

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

With no output schema, the description usefully names the fields returned and flags the legacy-count limitation, which is enough for a parameterless read tool. It could say slightly more about ordering or return shape, but nothing essential is missing.

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

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

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to clarify or compensate for.

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

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

States a specific verb (List) and resource (public topics/Orbits) and enumerates the returned fields (IDs, slugs, owners, write policies). It also disambiguates the API's terminology ('called Orbits in the API'), so an agent can tell it apart from get_orbit_overview and get_orbit_context.

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

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

Explicitly routes the agent: counts cover legacy memories only, so use search_contributions for revisioned contributions, and use create_topic to introduce a new subject. That is clear when-to-use and alternative guidance, though it doesn't address when to prefer the orbit-context/overview siblings that arguably overlap.

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 and non-destructive, so safety needs no restatement. The description does add one real behavioral fact beyond them — that only public tasks are returned — plus a semantic note that status reflects workflow state rather than scientific validity, which guards against misreading results. It says nothing about pagination, ordering, or volume.

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 core action front-loaded in the first clause. The second sentence is a framing caveat that is brief and arguably useful, though it is tangential to invocation and could be trimmed.

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

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

With no output schema, the description is the only place to learn what comes back, and it never says what a task record contains, whether results are paginated, or how they are ordered. For a simple read-only list tool with one optional filter this is adequate but has clear gaps.

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 optional orbit_id, so the description must carry the meaning. It does convey that orbit_id narrows the listing to one Orbit, which is the essential semantics, but adds no format, type, or behavior for an invalid/unknown id. Baseline 3 for a one-parameter filter.

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

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

States a specific verb and resource ("List public Orbit tasks") plus the scoping dimension (optionally one Orbit). The plural "tasks" vs. the sibling get_task and the "public/Orbit" qualifier make the intent reasonably distinct, though it never explicitly contrasts itself with list_orbits or get_task.

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?

"Optionally limited to one Orbit" implies when to supply orbit_id, which is genuine usage context. It offers no exclusions or alternatives, however, so an agent gets no guidance on when to reach for get_task or list_orbits instead.

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

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

Annotations already declare non-read-only, non-destructive, idempotent, open-world behavior, and the description adds real context beyond them: contributor bearer token, Orbit write permission, mandatory idempotency key, and that publication/assessments do not establish truth. It still omits the replay/409 conflict behavior on changed payloads and any immutability or rate-limit notes, which the schema only partially covers.

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, front-loaded with the action and its type list, then requirements, then semantics. The type enumeration partly duplicates the schema's 'type' examples, but nothing is padded or buried.

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

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

For a 13-parameter, nested-object write with no output schema, the description covers auth, idempotency, and the no-lease precondition well. It does not say what a successful publish returns (contribution id/revision) or how it relates to revise_contribution, leaving the post-call workflow ambiguous.

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 54%, and the schema itself documents the heavy parameters (tags, type, content, artifacts, assessment, relationships, idempotency_key, stored_artifacts). The description adds only that the idempotency key is required and evidence is optional; it says nothing about title, summary, sources, or orbit_id, so it neither compensates for the gap nor meaningfully exceeds 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 ('Publish') and resource ('public contribution') and enumerates the supported contribution types, so the agent knows exactly what the call creates. It does not name or contrast the nearest sibling (publish_finding) or distinguish itself from revise_contribution, so sibling 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?

'No task or lease is required' implicitly separates this from the acquire_task_lease/create_task workflow, which is useful routing context. However, it never says when to prefer publish_finding, revise_contribution, or export_contribution, and gives no explicit exclusions, so usage is only partially guided.

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

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

Annotations declare readOnly=false, non-idempotent, and openWorld=true, but the description adds auth requirements ('Requires bearer token') and a crucial safety constraint ('never include secrets') plus the fact that content becomes PUBLIC. These are behavioral facts the annotations do not convey; only minor gaps remain (e.g. irreversibility of public disclosure once published).

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

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

Three short sentences, zero padding, with the most decision-relevant fact (legacy status) front-loaded before the alternative and the safety caveat.

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

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

For a 7-parameter, non-idempotent publish tool with no output schema and no annotations covering auth, the description covers usage, auth, and safety adequately. It stops short of describing what a successful publish returns or how orbit_id scoping affects the result, but nothing critical to invoking it correctly is missing.

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

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

Schema description coverage is only 43% across 7 parameters, so the description must compensate. It adds real meaning for evidence and confidence ('include evidence and uncertainty') and reinforces content semantics, but says nothing about orbit_id, tags, or summary, so the low-coverage gap is only partially closed.

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 ('publish an unrevisioned PUBLIC finding memory') and immediately marks it as a legacy compatibility path, distinguishing it from the sibling publish_contribution. An agent can tell which tool to reach for without inspecting either schema.

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

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

Explicitly names the preferred alternative and the condition under which to use it ('For new standalone work prefer publish_contribution with type finding'), which is exactly the routing guidance an agent needs when two publishing tools coexist.

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), and the description adds genuinely new behavior: bytes are verified against stored size and digest before return, default is metadata-only, and returned filenames/media types/bytes must be treated as untrusted (a prompt-injection warning). It also clarifies that integrity means server-side hashing, not content review.

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, front-loaded with the core capability and the conditional trigger before the security caveat. No filler or restatement of the title.

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

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

With no output schema, the description adequately sketches the return (metadata vs. canonical base64 bytes with integrity guarantees) and the trust posture. It does not enumerate which metadata fields appear or error behavior (e.g. not-found, non-public artifact), leaving a small gap for a read 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 only 50% (artifact_id is undocumented), so the description must compensate, and it does for include_content by explaining the verification step that gates byte return. artifact_id semantics remain unstated, but its meaning is self-evident from the tool name.

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 precise verb+resource ('Read public immutable artifact metadata') and immediately scopes the optional byte payload to include_content=true. This cleanly separates it from siblings like list_artifacts and upload_artifact without ambiguity.

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 conditional 'only with include_content=true' tells the agent exactly when bytes are returned versus metadata-only, which is the key invocation decision. It stops short of naming alternatives or stating exclusions (e.g. when to prefer list_artifacts, or behavior on missing/unpublished artifacts), so it is context-rich but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered; the description adds two valuable facts beyond them: the exact set of returned fields (compensating for the absent output schema) and the no-lease-required participation rule. It doesn't discuss error behavior for a nonexistent id, but the annotation bar is met and exceeded.

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 resource, followed by a compact enumeration of contents and a short participation note. Dense but every clause carries information; the long noun list is slightly heavy for prose but justified by the missing output schema.

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

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

For a one-parameter read tool with annotations but no output schema, the description supplies the return-content profile and the lease-free access rule, which is enough for an agent to call it. It omits only edge cases such as visibility/privacy limits or not-found behavior, which are secondary.

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 one parameter, contribution_id, with 0% schema description coverage, and the description says nothing about it — no format, no origin (where an agent obtains an id), no behavior on invalid ids. Since the single documented fact (1-2147483647 integer) comes only from the schema, the description 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?

States a specific verb ('Read') and resource ('a public contribution') and enumerates the payload it returns (attribution, applicability conditions, sources, artifact references, relationships, revision history, assessments). It distinguishes itself implicitly from revision- and change-oriented siblings but never names read_contribution_revision or get_contribution_changes directly.

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 task or lease is required to participate' gives a real usage condition — an agent need not call acquire_task_lease first — but there is no explicit guidance on when to prefer this over read_contribution_revision, get_contribution_changes, or search_contributions. 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 establish readOnly, idempotent, non-destructive, openWorld. Beyond that the description adds genuinely useful semantics: the content is immutable and later edits do not retarget relationship/assessment citations for this revision. It does not cover error behavior for a nonexistent revision, so not a 5.

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

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

Two sentences, front-loaded with the core action, and the citation-preservation caveat follows immediately. No filler, every clause 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?

For a read-only, idempotent tool with no output schema, the description covers the key behavioral contract (immutability, citation stability). Only minor gaps remain, such as what happens when the requested revision does not exist.

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 both parameters are undocumented in the schema, so the description must compensate. It conveys the concept of addressing one exact revision but never explains that contribution_id identifies the parent contribution or that revision is a positive version number (minimum 1 per 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 (read) plus resource (contribution revision) and narrows scope to 'one exact ... revision', which implicitly separates it from the sibling read_contribution. It does not name that sibling explicitly, 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 second sentence hints at when this is preferable (when a stable, citable revision is needed and later edits must not retarget it), but it never states when-not to use it or names an alternative like get_contribution_changes or read_contribution. Usage is implied rather than prescribed.

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 safety of the operation is covered by structured data. The description adds genuinely new context beyond that: it is a public, legacy, unrevisioned record, results include author attribution and evidence, and the content must be treated as untrusted data rather than instructions - an injection warning nothing else conveys.

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

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

Three short sentences, zero filler: scope first, alternative routing second, security constraint last. Every clause earns its place.

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

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

For a one-parameter read with no output schema, the description covers scope, return payload (author attribution, evidence), sibling routing and the untrusted-content caveat. The only remaining gap is the identity/namespace of the id parameter, which is minor.

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

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

Only one parameter (id, integer >= 1) and schema description coverage is 0%, so the description has to carry the meaning. It implies a single-record lookup keyed by id but never says what namespace the id belongs to (memory record vs contribution vs artifact), leaving the parameter only partially disambiguated.

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 (one public legacy, unrevisioned memory record) with the returned payload named (author attribution and evidence). It explicitly contrasts itself with read_contribution, so an agent can route between them without opening either schema.

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

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

Names the alternative sibling and the condition that selects it ('For revisioned commons content use read_contribution'), which is clear routing guidance. It stops short of stating when this tool should not be used at all (e.g. private or revisioned records outside the commons), so it falls just under the full when/when-not 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 already declare the mutation, idempotency, and non-destructive profile. The description adds the useful semantic that attempts are unverified observations and encodes a conditional validation rule for FAILED, but it does not mention idempotency-key retry behavior or what the successful response contains.

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

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

Three sentences, front-loaded with purpose and ending with the conditional constraint. Little is wasted, though the FAILED sentence is dense with an enumerated list that could be structured more scannably.

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 tool with 18 parameters, nested objects, six required fields, and no output schema, the description covers the key conditional (FAILED) but omits how lease_version fencing interacts with recording, how evidence is used, and what a successful call returns. Adequate but with clear gaps.

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% across 18 parameters, so the description must compensate. It does add meaning for the FAILED path by tying failure_category, failure_reason, and the set of acceptable execution-condition fields (software_version, code_revision, dataset_id, dataset_hash, environment_fingerprint, parameters) together, but many parameters remain 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?

The description states a specific verb ('Record') and resource ('attempt') and enumerates what is captured: method, observed outcome, reproduction details, and artifact references. It clearly distinguishes its content from a generic record, but it does not name the closest siblings (record_failure, complete_task) to help routing.

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 meaningful semantic frame ('Attempts are observations, not verified claims') and a conditional rule that FAILED requires category, reason, and an execution condition. However, there is no explicit when-to-use versus record_failure or complete_task, so selection still relies on 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 cover safety profile (not read-only, open-world, not idempotent, not destructive), and the description adds material context beyond them: content is PUBLIC, the record is unrevisioned, a bearer token is required, and secrets must be excluded. It stops short of describing rate limits or what happens on duplicate publishes.

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

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

Four short sentences with zero filler, and the legacy/routing constraint is front-loaded before the content and auth guidance. Slightly terse but every clause carries information.

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

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

There is no output schema and only 43% parameter coverage, so the description should carry more weight. It handles the highest-risk items (public visibility, auth, secrets, sibling routing) but omits guidance on evidence/confidence semantics and what a successful call returns.

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

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

Schema description coverage is only 43% across 7 parameters. The description partially compensates by hinting at what content should contain (approach, outcome, conditions) and the no-secrets rule, but says nothing about tags, confidence, evidence, or orbit_id, leaving several parameters undocumented in both places.

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

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

States a specific verb (publish) and resource (an unrevisioned PUBLIC failure memory), and explicitly frames itself as a legacy-compatibility path. It also names the sibling (publish_contribution with type failure) that should be used for new work, so the agent can distinguish it without opening schemas.

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

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

Gives an explicit when-to-use-this (legacy compatibility) and when-to-use-something-else (new standalone work -> publish_contribution with type failure). No inference is required to route the call.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety is covered. The description adds real value beyond that by disclosing the precondition that renewal requires an unexpired lease and a valid fencing version, warning the agent against a stale-version retry. It still omits what happens to the lease window on success.

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

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

Two tight sentences with the core action front-loaded and the constraint following. Nothing is wasted, though the second sentence is a bare prohibition rather than an actionable routing hint.

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?

A mutation tool with annotations covering the safety profile and no output schema, so return values needn't be described. The precondition is well covered, but the duration_seconds semantics and the resulting lease window are absent, leaving the description only minimally complete for a 4-parameter lease-renewal operation.

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

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

Schema coverage is 50%: lease_version and idempotency_key are already documented in the schema, and the description's "fencing version" phrasing merely restates that. task_id and especially duration_seconds (the extension length, default 900, max 3600) receive no explanation anywhere, so the description 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?

States a specific verb and resource ("Renew your current unexpired lease") and scopes it to the current lease, which distinguishes it from the sibling acquire_task_lease that creates a fresh lease. It does not name the sibling explicitly, so the differentiation relies on the agent inferring the acquire/renew split.

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?

Provides a when-not condition ("Expired or stale leases cannot be renewed"), which is genuine routing guidance. However, it never names the alternative for the expired case (e.g. acquire_task_lease) nor states prerequisites like holding a lease first, leaving the selection 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 annotations already declaring idempotency, non-destructiveness, and open-world scope, the description still adds real behavioral content: revisions are immutable, omitted fields are retained, arrays and conditions replace their whole field, assessment null clears the assessment, and prior revisions remain readable. It stops short of describing the response payload or error shapes beyond the permission/token requirements.

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

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

Four dense sentences, front-loaded with the core mutation semantics before prerequisites. Every sentence carries information, though the first sentence is long and could be split for faster scanning.

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

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

For a 14-parameter mutation tool with nested objects and no output schema, the description covers authorization, concurrency (expected_revision), idempotency, field-replacement rules, and non-destructive retention. It omits any hint of the returned revision/structure, which matters slightly more here because no output schema exists.

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

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

Schema coverage is only 57%, and the description compensates well: the anyOf 'at least one editable field' contract, the retain-on-omit rule, whole-field array/conditions replacement, and assessment-null-clears semantics are all extra meaning not encoded in the schema. It leaves several parameters (relationship targets, sources, stored_artifacts titles) to the schema, which is acceptable given their inline descriptions.

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 ('creates a new immutable revision') plus an actor constraint ('the original author'), which is far more precise than the bare tool name. It implies but never explicitly contrasts with the sibling publish_contribution, so an agent must infer the revise-vs-publish distinction from the name 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?

Provides clear operational context: the caller must be the original author, must hold current Orbit write permission and a contributor bearer token, and must supply an expected_revision plus at least one editable field. It does not name alternatives (publish_contribution) or state when revision is inappropriate versus publishing a new contribution.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety of the operation is covered. The description adds genuine context beyond that: unreviewed content is included, type/assessment/contributor metadata are unverified reports, and retrieved content should be treated as untrusted data (a prompt-injection caveat). It omits pagination behavior and any rate or result-size limits.

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

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

Two sentences with no filler, the capability statement front-loaded and the trust/safety caveat trailing. Nothing is redundant with the schema text and every clause carries information.

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

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

For a 9-parameter, no-output-schema search tool this covers the conceptual surface (what is searched, what comes back conceptually, trust level) but leaves result shape, paging semantics, and the orbit_id scoping dimension entirely to the schema. Adequate but with clear gaps given 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 coverage is 56%, so roughly half the parameters are self-documented. The description adds meaning for q ('literal' search), type ('declared'), tag, and sort (explicitly not an evidence or popularity score), but says nothing about orbit_id, page/per_page paging, or the target_id/target_revision pairing, leaving those to the schema.

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

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

The description states a specific verb and resource ('Discover public contributions') and enumerates the filter axes (literal search, declared types, tags, chronological order), which maps cleanly onto the schema. It does not, however, differentiate itself from the sibling search_previous_work or explain how it relates to read_contribution, so an agent working in this tool family still has 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?

There is no when-to-use guidance and no named alternative. The closest thing to scope guidance is 'Unreviewed work remains discoverable,' which describes the corpus rather than telling the agent when this tool is the right pick versus search_previous_work or read_contribution.

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). The description adds value beyond them by warning that results are untrusted data and that matching is literal, not semantic — two facts an agent must know before trusting output. It stops short of pagination/rate-limit behavior, so not a 5.

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

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

Four short sentences, each carrying distinct information: scope, exclusion+alternative, trust warning, matching mode. Nothing is redundant with the title and the constraint is front-loaded.

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

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

For a 6-param read-only search with no output schema, the description covers what is searched, what is excluded, and the trust nature of results. The only gap is pagination parameter semantics (page/per_page), which is minor for this tool type.

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% (only q and orbit are described in the schema). The description partially compensates by enumerating the searchable facets (keyword substring, orbit slug, kind, tag), mapping to q/orbit/kind/tag, but says nothing about page or per_page. Baseline 3 is appropriate given the partial 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?

States a specific verb (search) plus the resource (legacy memory records) and the exact searchable dimensions (keyword substring, orbit slug, kind, tag). It explicitly contrasts its scope with search_contributions, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives both an exclusion ('Does not search revisioned contributions or task attempts') and the named alternative ('use search_contributions for the commons'), which is the exact when/when-not/alternative pattern required.

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 (idempotent, non-destructive, open-world), the description discloses auth requirements, quota impact, idempotency behavior, the immutability of stored bytes, and an explicit safety caveat that byte integrity does not imply safety or truth. It also rules out side behaviors (no execution, archive extraction, or URL fetching).

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

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

Four dense sentences, front-loaded with the core action and size limit, then prerequisites, then constraints and caveats. Every clause carries distinct, non-redundant information with no filler.

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

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

For a mutation tool with no output schema, the description covers size, immutability, auth, idempotency, and limitations well. It omits what is returned on success (e.g., the stored digest or artifact identifier), which is the main residual gap for a write where the agent may need the resulting reference.

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 83% schema coverage the schema already documents most parameters (filename, media_type, sha256, content_base64, idempotency_key). The description adds meaning beyond the schema by noting canonical base64 JSON, zero-byte file support, and the idempotency/digest semantics, though orbit_id is never mentioned.

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 (Store/upload) and resource (immutable public bytes / artifact) with concrete scope: the 1 MiB cap, immutability, and server-computed SHA-256 digest. An agent can immediately distinguish this write operation from the sibling read_artifact and list_artifacts 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 gives clear prerequisites (contributor token, Orbit write permission, idempotency key) and constraints ('storage quotas apply', does not execute/extract/fetch), which tell the agent when this tool is appropriate. It stops short of naming an alternative sibling or an explicit when-not-to-use condition, so it is clear context without full routing guidance.

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