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

With no annotations, the description carries the full burden, and it does disclose meaningful traits beyond structured data: the operation is atomic, it is a lease (time-bound), and it can be renewed. It omits critical behavior — what happens on a version mismatch, whether the claim blocks other agents, and what occurs when the lease expires.

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 action and its constraint front-loaded and the precondition second. No filler or restatement of the name.

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

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

A mutation tool with five parameters, zero schema coverage, no annotations, and no output schema needs far more: expected return value (lease granted? new version?), conflict/error behavior, and parameter meanings are all missing. The description leaves the agent guessing on anything past the happy path.

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

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

Schema coverage is 0%, so the description must compensate. It does convey the lease_seconds bounds (30–86400), which the schema itself does not constrain, and it implies expected_version semantics via "read its latest version first." It says nothing about agent_id, project_id, or the conflict meaning of expected_version.

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

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

The description uses a specific compound verb ("claim or renew") with a clear resource ("task") and adds scope detail (30–86400 second lease). An agent can distinguish this from update_task or create_task. It loses a point only because it never explicitly contrasts itself with those siblings.

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

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

"Read its latest version first" is a real prerequisite hint implying an optimistic-concurrency read-then-claim flow. However, there is no guidance on when to claim versus renew versus update_task, and no exclusions or failure conditions 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that 'identical retries are safe,' which is meaningful idempotency context. However, it does not say what happens on slug conflicts, whether permissions are required, or whether the slug is immutable after creation.

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

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

The definition is a single front-loaded sentence with no filler. The slug constraint and idempotency note are both packed efficiently into it.

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

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

For a creation tool with no annotations, no output schema, and 0% parameter description coverage, the description is too thin. It says nothing about required inputs beyond the schema, duplicate handling, permissions, or what the caller receives after creation.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It clarifies project_id as a lowercase stable slug, but leaves name and description without semantic detail or constraints. One of three parameters is meaningfully explained, which is insufficient at this coverage level.

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: 'Create a project.' The added mention of a 'stable lowercase slug' makes the kind of project identifier clearer. It does not explicitly distinguish itself from siblings such as create_task or list_projects, but the resource noun does most of that work.

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 guidance on when to use this tool versus alternatives like list_projects or create_task. It also omits prerequisites, such as permissions or whether the project must be absent before creation.

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?

No annotations are provided, so the description carries the full burden. It does disclose two useful behaviors beyond the schema: the created task starts in a 'pending' state, and request_id enables idempotent retries. It omits permissions/auth requirements, what happens when the same request_id is replayed, and what the call returns.

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

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

Two short sentences with zero filler; the core action is front-loaded and each clause adds distinct guidance (retry safety, deduplication).

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 six-parameter mutation tool with no annotations and no output schema, the description is thin: no permission requirements, no return shape, and most parameters unexplained. Only the deduplication and retry story is adequately covered.

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

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

Schema description coverage is 0% across six parameters, so the description must compensate, and it only explains request_id (idempotency key for retries). The meaning of files, description, and the required project_id/agent_id/title pairing is left entirely to bare schema titles.

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

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

The description gives a specific verb and resource ('Create a pending task') and states the resulting state, which separates it from siblings such as claim_task, update_task, and create_project. It does not explicitly name those alternatives, but the operation is unambiguous.

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

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

It gives concrete when-to guidance: check list_tasks first to avoid duplicating existing work, and supply request_id for safe retries. It stops short of exclusions, e.g. when to use update_task or claim_task instead, so it is clear context without full routing rules.

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?

No annotations are supplied, so the description carries the burden. 'Bounded overview' and 'recent' disclose scoping and result-size behavior, but read-only status, permissions, and output shape are only implied, leaving meaningful gaps.

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

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

It is one front-loaded sentence with no filler. The brevity works at the sentence level, even though the overall definition is under-specified elsewhere.

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 annotations, no output schema, and 0% parameter description coverage, the one-sentence description leaves key calling details such as project scope, limit behavior, and return shape unstated. It is not complete enough for a two-parameter context tool.

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

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

Schema coverage is 0%, and the description never mentions project_id or limit. 'Bounded' loosely hints at limit, but it adds no real parameter meaning, leaving both inputs undocumented.

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

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

The description names the content categories (recent work, decisions, handoffs, open tasks) and 'Start here' signals its role as an entry point. It stops short of naming or contrasting sibling tools such as search_context or get_updates, 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?

'Start here' gives an explicit entry-point recommendation, which is useful routing context for an agent. It does not state when not to use it or name alternatives, so it lacks the full guidance of a 5.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: ordering is oldest-first, items are fetched after a cursor, and iteration should continue while has_more is true. It omits what an event contains, whether requires_project access is scoped, rate limits, and whether the caller's own actions appear in the stream.

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 read semantics and the pagination loop front-loaded; nothing is padded or redundant. It borders on under-specification, but every sentence does carry operational weight.

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 annotations and no output schema, the description partially compensates by naming the return fields next_cursor and has_more and describing the loop that consumes them. It still leaves the required project_id scope and the limit parameter unexplained, which is a material gap for a multi-tenant event feed.

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 descriptions must compensate for all three parameters, but only after_event_id is obliquely implied by 'after a cursor' — and the description calls it a cursor while the schema calls it an integer event id, which is a naming mismatch the agent must resolve. project_id and limit receive no meaning at all, including no explanation of limit's default of 30 or its interaction with has_more.

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 events') plus the ordering and cursor anchor ('oldest first after a cursor'), which is far more than the bare name get_updates conveys. It does not distinguish itself from siblings like get_context or search_context, so the agent has to infer the boundary 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?

'continue while has_more' gives clear in-loop pagination guidance, which is genuinely actionable. However, there is no statement of when to choose this over get_context/search_context, nor any prerequisite or exclusion, so cross-tool selection is left implied.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses only that results are paginated via a "next_offset" field that terminates at null. It omits return shape, default page size, whether the list is filtered by permission, and ordering, and the referenced "next_offset" does not correspond to any parameter in the schema.

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

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

Two short sentences with no filler, and the purpose statement is front-loaded before the pagination note. Brevity is undercut slightly by the undefined "next_offset" reference, which adds words without adding clarity.

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

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

For a tool with no annotations, no output schema, and zero schema description coverage, the description is far too thin to let an agent call it confidently. It should at minimum explain limit/offset semantics, the default page size, and what a returned project entry contains.

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

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

Schema description coverage is 0%, so both parameters (limit, offset) are undocumented anywhere, and the description does not explain either one. Worse, it points the agent at "next_offset" rather than the declared "offset" parameter, creating ambiguity about how to advance pages.

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?

"Find shared projects" names the resource but uses a vague verb and never defines what "shared" means, so an agent cannot tell whether this lists the caller's projects, projects shared with them, or team-wide projects. It also does not differentiate itself from siblings such as create_project or get_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?

There is no statement of when to use this tool versus alternatives like get_context or create_project, and no prerequisites or exclusions are given. The only guidance is pagination mechanics, which is not usage selection.

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

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

With no annotations supplied, the description carries the full behavioral burden; the word "Read" weakly implies read-only, which is useful but unconfirmed. It says nothing about pagination defaults, ordering, permissions, or what the response contains for a 4-parameter listing tool.

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

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

The description is two short sentences with no filler and the read intent is front-loaded. However, the brevity comes at the cost of nearly all useful information, so it reads as under-specification rather than disciplined concision.

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 four parameters, a required project scope, pagination controls, no annotations, and no output schema, this description is far too thin. An agent could not confidently determine what is returned or how to page through results from this text alone.

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

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

Schema description coverage is 0%, so the description should compensate, but it only repeats the status enum values already present in the schema. The required project_id, limit, and offset parameters receive no explanation of meaning, defaults, or interaction.

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 says "Read task versions and owners," which signals a read operation on task data, but it never states plainly that this lists tasks in a project, and the phrase "versions and owners" is ambiguous about what is actually returned. It does not distinguish the tool from siblings such as get_context, search_context, or get_updates.

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 explicit when-to-use guidance and no mention of alternatives among the nine sibling tools (e.g., create_task, claim_task, update_task). The only implicit guidance is the status filter enumeration, which hints at filtering but not at when this tool should be chosen.

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 no annotations, the description carries the full load; it does disclose meaningful traits: append-only semantics, idempotent retry behavior via request_id, and the fact that no code inspection or test execution occurs. It does not cover permission/auth requirements, what happens when a duplicate request_id arrives, or what the call returns (no output schema), leaving real gaps for a write tool.

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

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

Three short sentences, each doing distinct work: the action and kinds first, then field-filling guidance, then the non-execution boundary. No filler, no repetition of the schema, and the most important information 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 nine-parameter, 0%-coverage, annotation-free write tool with no output schema, the description covers the high-value fields but omits the identity/scoping parameters and any indication of the response. It is workable but leaves enough unaddressed that an agent may guess at project_id/agent_id/task_id semantics.

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

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

Schema description coverage is 0%, so the description must compensate: it explains request_id (retry safety), details (rationale/tests/next steps), files (relative paths) and git_ref (commit/branch), and enumerates the kind values. However, three of nine parameters — project_id, agent_id, and task_id — get no explanation at all, so coverage is partial for a nine-parameter tool.

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

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

States a specific verb ("append") and the record types it accepts, listing the exact kinds (progress, decision, handoff, blocker, test, note) that map to the `kind` enum. It is clearly a write of an update entry, distinguishable from read siblings like get_updates and from task-mutation siblings like update_task, 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?

Gives concrete guidance on how to call it (use request_id for safe retries; put rationale/tests/next steps in details; reference relative files and a commit/branch) and one clear boundary ("does not inspect code or execute tests"), which steers agents away from expecting verification. It stops short of stating when to prefer this over update_task or when a record should not be written at all.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only search and hints at pagination via next_before_event_id, but does not disclose permissions, result format, limit behavior, or search semantics such as case sensitivity.

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

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

The description is short and front-loaded, with no wasted words. However, the second sentence is cryptic and under-specified, making the overall structure less helpful than its brevity suggests.

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

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

For a four-parameter search tool with no annotations and no output schema, the description is incomplete. It gives the basic purpose and a pagination hint but omits parameter meanings, return behavior, and usage context relative to siblings.

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

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

Schema description coverage is 0% for four parameters, and the description does not compensate. It vaguely maps query to literal text and references next_before_event_id, which is not even a parameter name (the schema has before_event_id), while project_id, limit, and before_event_id 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 and resource: "Search literal text in summaries, details and files." This makes the tool's core purpose clear, though it does not explicitly distinguish it from sibling tools like get_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?

There is no guidance on when to use this tool versus get_context or other siblings, and no exclusions are stated. "Follow next_before_event_id" is a pagination hint rather than usage 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?

With no annotations supplied, the description carries the full burden and does substantial work: it discloses lease side effects per status (pending releases, completed finishes, blocked retains, in_progress/blocked do not renew) and the optimistic-concurrency requirement. Gaps remain on auth/permission requirements and on what a version conflict does at runtime, but the non-obvious behavioral traits are surfaced.

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

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

Four short sentences, front-loaded with the core lease semantics, with no filler. The telegraphic style ('pending releases, completed finishes') is dense but readable; slight loss from clipped phrasing and the use of two separate sentences to restate lease behavior.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description needs to cover the return contract, and it does not — an agent cannot tell whether the new version needed for the next update comes back in the response. Version-conflict failure behavior is also left implicit, though the lease and summary semantics are well covered.

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

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

Schema description coverage is 0% across six required params, so the description must compensate. It explains summary ('completion evidence, blockers or a handoff explanation'), ties 'latest version' to expected_version, and gives semantics for three of the four enum statuses, but leaves agent_id, task_id, and project_id completely undefined.

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 ('Update') and a specific resource ('your live claim' on a task), and the status-transition phrasing separates it from claim_task, which acquires a claim rather than modifying one. It never names a sibling tool explicitly, so the differentiation is inferable rather than stated.

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

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

'All changes require the latest version' gives a real prerequisite for calling the tool, and 'your live claim' implies a prior claim_task call. However, there is no guidance on when to use this versus record_update for progress notes, and no statement of what to do on a stale-version rejection.

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