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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond them: results are chronologically ordered and authors are classified as agent or human. It says nothing about pagination, result size, or authorization scope for a read tool that may span many changes.

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

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

A single front-loaded sentence with no filler. The endpoint reference is somewhat redundant for an agent but reinforces parameter meaning, so it earns a modest 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 simple read-only tool with one required parameter and no output schema, the description covers purpose and authorship semantics but not the shape of the returned history (entries, timestamps, ordering across agents vs humans) or bounds on result size. Adequate but with visible 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?

Only one parameter (id) with 0% schema description coverage, so the schema gives no explanation. The description indirectly documents it by embedding the REST path GET /actions/{id}/history, clarifying that id identifies the action whose history is fetched. However it adds no format or validity detail beyond that inference.

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

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

Names a specific resource (one action's history) and specifies the content (chronological changes and who made each, agent or human), which distinguishes it from forbiz_get_action. The verb is implicit in the noun phrase rather than an explicit action word, but an agent can tell what it retrieves.

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

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

The description implies the use case (auditing an action's change sequence) but never states when to choose this over the clearly related sibling forbiz_get_action, nor any prerequisites. Usage is inferable but not 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 only give the bare safety profile (write, non-destructive, open-world), so the description carries meaningful extra weight: append-only semantics, no automatic promotion to workspace truth, and the guarantee that a contradiction never erases the item it contradicts. These are real behavioral commitments an agent cannot get from the annotations. Auth requirements, rate limits, and error behavior remain 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?

Two sentences, front-loaded with the action and its content categories, followed by the single most important behavioral caveat. The parenthetical endpoint adds orientation at no length cost, and there is no filler.

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

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

For a mutation tool with no output schema, the description covers the core epistemic contract but omits practical essentials: whether it returns evidence ids (which the schema's contradictsEvidenceId field implies are needed for follow-up calls), whether items are validated or partially rejected, and how it relates to forbiz_find_evidence. Adequate, but an agent could still call it incorrectly on the first try.

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

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

The description says nothing about the single 'items' parameter — not that it is a batch array, nor anything about the kind/epistemicStatus enums, confidence, or materialToDecision. With schema description coverage reported at 0% for the top-level property and a complex nested enum surface, the description does not compensate; the agent must read the schema and infer enum semantics on its own.

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 (append) and resource (evidence), and enumerates the input kinds ('what you observed, were told, inferred or decided'), which lets an agent distinguish this write tool from the read-side sibling forbiz_find_evidence. It does not name that sibling 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?

The four content categories ('observed, were told, inferred or decided') imply when to record evidence, and 'nothing becomes workspace truth automatically' hints that this is a raw capture step. However, there is no explicit when-to-use vs when-not, no mention of forbiz_find_evidence or forbiz_record_signal as alternatives, and no guidance on batching multiple items.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description still adds real value: it discloses the per-agent payload (activity plus a track record over created/executed/signal-recorded/outcome/overdue) and the important limitation 'Counts only, no ranking.' It stops short of disclosing pagination or exact 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 dense sentence, front-loaded with the resource and its metrics, with the endpoint appended. Slightly run-on with the colon list, but every clause carries information and nothing is wasted.

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

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

With only one optional parameter, no output schema, and annotations covering safety, the description adequately conveys what the tool returns and its counts-only scope. It could say more about granularity or ordering, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%; the single 'days' parameter is fully documented in the schema ('Window in days, default 30'). The description adds no extra meaning about the window, so the baseline 3 applies.

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

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

States the resource (every agent of this workspace) and enumerates the specific activity metrics returned: created, executed, signal recorded, outcomes, overdue. This is a clear verbless-but-specific retrieval description that an agent can act on, though it never explicitly differentiates itself from siblings like forbiz_me or forbiz_state.

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

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

Usage is only implied: the roster-plus-tally framing suggests it is an overview tool, and 'Counts only, no ranking' hints at its scope. There is no explicit when-to-use statement and no named alternative for getting per-action or per-user detail.

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

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=true, readOnlyHint=false = a mutation with no destructive risk). The description adds non-obvious behavioral facts beyond that: that recording 'found' closes nothing, and the specific field obligations attached to each result value. These are meaningful, non-schema behavioral disclosures.

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

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

Dense, front-loaded sentences with no filler; the behavior for each result state is stated tersely. The parenthetical endpoint is slightly redundant since the tool name already implies the resource, but overall it wastes little.

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 tool with 7 params, 43% schema coverage, nested objects, and no output schema, the description covers the result-dependent behaviors and the key alternative well but omits what note and looked_for are for and how they interact with the result states. Adequate but with visible 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 43% across 7 params, so the description is required to compensate. It does explain the conditional semantics of result values (not_found_in_source needs source+period; cannot_check needs reason) and the meaning of source/period ('where you looked and when'), but leaves note, looked_for, and id semantics unaddressed.

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 ('Record that you looked for the expected signal') and anchors it to the endpoint POST /actions/{id}/signal-checks, so the agent knows exactly what action is taken. It names forbiz_record_signal as the tool for linking a found signal, giving partial sibling differentiation, though it never addresses the closely-related forbiz_close_without_signal.

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 conditional guidance: not_found_in_source requires source+period, cannot_check requires reason, and 'found closes nothing; link the signal with forbiz_record_signal' explicitly routes a finding to the alternative tool. It stops short of full when-to-use/when-not coverage (e.g. no boundaries against close_without_signal), but the routing to a sibling is genuinely present.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the post-claim continuation behavior, which is genuinely useful, but omits whether the link is single-use, expiring, or requires authentication — meaningful gaps for a credential-bearing link.

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: the first defines the artifact and endpoint, the second gives the action and consequence. Zero filler and the key behavior 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?

With no input parameters and no output schema, the description covers what the tool is and what to do with the result. The only missing piece is link validity semantics (expiry, single use), which is a minor omission for this 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?

The tool takes no parameters, so the baseline is 4; the description correctly introduces no parameter discussion and there is nothing to clarify.

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?

Names a specific artifact (a claim link for the human owner to take ownership of a provisional workspace) and includes the HTTP endpoint, so the agent knows exactly what the tool produces. It is clearly distinct from siblings like forbiz_state or forbiz_me, though it doesn't explicitly contrast itself with any of them.

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

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

"Give it to the owner; the agent keeps working after the claim" states the intended audience and the lifecycle consequence, which is actionable context. There's no explicit when-not-to-use or alternative routing, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds only the HTTP verb/path; it says nothing about reversibility, what 'closing' an action does to its state, or whether a learningNote is retained, which is what would earn credit 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?

A single compact sentence with the action and endpoint front-loaded and no filler. It is efficient, though bordering on under-specified rather than merely concise.

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, open-world tool with no output schema and zero schema description coverage, the definition is too thin. An agent cannot tell how this differs from forbiz_close_without_signal, what the outcome enum means, or what happens to the action afterward.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It implies id (via the {id} path) and outcomeStatus ('with its outcome'), but never explains the four enum values (expected/partial/unexpected/deferred) and never mentions learningNote at all.

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

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

States a specific verb and resource ('Resolve an action with its outcome') plus the underlying endpoint, so the agent knows this is a write that closes an action loop. It does not distinguish itself from close alternatives in the sibling list such as forbiz_close_without_signal or forbiz_mark_executed, leaving that inference to the agent.

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

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

There is no when-to-use guidance, no precondition, and no named alternative. The most obvious alternative, forbiz_close_without_signal, is never mentioned even though the two names are nearly identical, forcing the agent to guess which close path applies.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description adds that a reason is expected and that silence ('no signal') is a valid outcome distinct from rejection, but it does not say what closing does to the action's state, whether the reason is required, or whether the close is reversible.

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

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

Front-loaded with the action and condition, then the endpoint and a short rationale. The tagline 'Silence is not rejection: say what you know' is somewhat motivational rather than operational, keeping it just short of a 5.

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

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

For a 3-param mutation tool with no output schema and 0% schema coverage, the description conveys the trigger condition and endpoint but omits the semantics of learningNote, whether reason is mandatory, and what a successful close returns or changes. Adequate but with notable 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%, so the description must carry the parameter burden. 'Saying why' loosely maps to 'reason', but 'learningNote' and the required 'id' are never explained, and there is no format, length, or required/optional guidance for either string.

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

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

Specific verb+resource ('Close an action') plus the exact condition that selects it over the sibling 'forbiz_close' ('that will not get a signal'). An agent can distinguish this from forbiz_close without opening either schema.

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

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

The description clearly states the context for use: an action that will never receive a signal, and that you must explain why. It implies but does not explicitly name the alternative (forbiz_close / forbiz_record_signal) that applies when a signal is expected, so routing is slightly inferential.

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

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

Annotations only declare mutation, open-world, and non-destructive; the description goes well beyond that by disclosing two distinct 409 failure modes (COMMITMENT_ALREADY_OPEN, POSSIBLE_DUPLICATE), the resume semantics of the first, and the confirm_new override for the second. This is exactly the kind of error/retry behavior an agent needs and cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with purpose, then the two error paths in the order an agent would encounter them. No filler and no restatement of the title.

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

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

For an 11-parameter mutation tool with nested objects and no output schema, the description covers the flow, the required fields, and both refusal paths. The one gap is the successful return shape — the description explains what a 409 body returns but not what a created commitment looks like, which matters given there is no output schema.

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

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

Schema coverage is already 82%, so the baseline is 3, but the description adds real meaning: commitmentKey is glossed with a concrete example ('acme/quote-followup') and its stability requirement, expectedSignalAt is tied to the expected-signal concept, and confirm_new's override role is restated in context. It doesn't touch roi, verb, or dueAt, but those are handled in the schema.

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

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

States a specific verb and resource ('Record an action you will take or took, with the signal you expect back') and pins the endpoint (POST /actions). The commitmentKey/expectedSignal framing clearly separates it from siblings like forbiz_record_signal or forbiz_close, which deal with signals and closure rather than opening a commitment.

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 operational routing: always send commitmentKey and expectedSignalAt, resending the same key is the documented way to resume, and confirm_new true should only be used 'if it is a different objective.' It stops short of naming sibling alternatives (e.g. when to use forbiz_record_signal vs this tool), which keeps it out of 5 territory.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description usefully adds what each returned item carries (source, contradiction and supersession pointers), which is behavioral context beyond the annotations, though it says nothing about ordering, paging, or result limits for a potentially large corpus.

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 front-loaded and the return-shape note second. No filler, though it is arguably slightly under-specified rather than optimally concise.

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 partially compensates by sketching the item shape, and read-only annotations cover the safety profile. However, two of four parameters and the semantics of the contradiction/supersession pointers remain unexplained, leaving gaps for an agent assembling a query.

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%: status and materialOnly have no schema description, and the description does not explain them either. "by text or subject" merely restates the already-documented q and subject fields, so the description does not compensate for the undocumented half of the 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 and resource ("Recover evidence") plus the two axes it can be queried by (text or subject) and the HTTP route. It is distinguishable from the write-side sibling forbiz_add_evidence, but it never contrasts itself with forbiz_search, which sounds like an overlapping retrieval tool.

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

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

The phrase "by text or subject" hints at how to query, but there is no statement of when to prefer this over forbiz_search or forbiz_add_evidence, and no prerequisites or exclusions. The agent is left to infer routing entirely.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context by naming the fields returned (expected signal, dates, lifecycle, outcome) and the underlying endpoint, which matters because there is no output schema. It does not cover auth or error 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?

A single front-loaded sentence with the resource and return contents stated first and the endpoint kept as a parenthetical. Nothing is redundant or padded.

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 no output schema, the description compensates by listing the shape of the returned state. What remains thin is routing guidance against lookalike siblings and any error/not-found behavior.

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

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

One parameter at 100% schema coverage; the schema already documents 'id' as the Action id. The description's '(GET /actions/{id})' only restates the path template and adds no format, sourcing, or lookup guidance beyond 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 and resource: read the full state of one action, identified by id. The enumeration of what 'full state' contains (expected signal, dates, lifecycle, outcome) distinguishes it from vague siblings like forbiz_state, though it never names a sibling 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 implied rather than stated: an agent infers it should call this when it has an action id and needs the complete record. There is no explicit when-to-use, no exclusion, and no pointer to alternatives such as forbiz_action_history or forbiz_state, which is a real ambiguity given the sibling list.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the write/safety profile is covered. The description adds the meaningful behavioral rule that this records an event that already occurred rather than scheduling one, but is silent on idempotency, whether the action can be re-marked, and any required auth or evidence preconditions.

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

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

Front-loads the action ('Record that the action really happened'), adds the endpoint for lookup, then one emphatic caution sentence. No filler, though the endpoint path is somewhat redundant with the tool name.

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

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

For a mutation tool with no output schema and modest annotations, the description covers the core intent and a key precondition. It leaves open what the call returns, whether marking is idempotent/repeatable, and how expectedSignalAt interacts with the recorded execution, which an agent invoking this state-changing endpoint would want.

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

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

Schema coverage is 67%, and the schema itself carries the notable constraint ('at most 5 minutes in the future') and the ISO 8601 format for expectedSignalAt. The description only implies that 'id' is the action identifier via the endpoint path and adds no meaning to executedAt or expectedSignalAt, so it neither compensates for the coverage gap nor regresses below baseline.

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

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

States a specific verb+resource ('record that the action really happened') and pins it to the endpoint POST /actions/{id}/execute, so the operation is unambiguous. It does not name or contrast itself with adjacent siblings such as forbiz_add_evidence, forbiz_record_signal, or forbiz_close, which is the only thing keeping it from a 5.

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

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

Gives a strong precondition ('Only when it did: never mark as executed without evidence that the act occurred'), which tells the agent the required state before calling. However, it never routes to alternatives (add_evidence, check_signal, close_without_signal) or says what to do when evidence is absent, so the guidance is implied rather than explicit.

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

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

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds value by enumerating what the call surfaces (identity, capabilities, plan, limits) and by implying the credential-scoped nature of the result. It does not discuss error behavior or auth prerequisites beyond 'current credential', so it is good but not exhaustive.

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

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

Two short sentences, zero waste. The payload inventory comes first and the operational instruction ('Call this first.') is front-loaded and easily scanned.

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

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

There is no output schema and no parameters, so the description carries the burden of describing the return — which it does by listing workspace, identity, capabilities, plan and limits. That is enough for an agent to know what it gets back, though field-level detail is absent.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description appropriately spends its words on the return payload instead of nonexistent inputs.

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 specific resource returned — workspace, agent identity, capabilities, plan and limits for the current credential — and the GET /me endpoint anchors it. It implicitly distinguishes itself from the sibling forbiz_agents by scoping to the caller ('current credential'), though it never names that sibling 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?

'Call this first.' gives a clear, actionable ordering instruction that tells the agent when this tool belongs in a sequence. It stops short of naming alternatives or exclusions, but the startup framing is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it returns a single prioritized item rather than a list and that it includes a handoff, which is genuinely useful beyond the annotations, but it stops short of explaining what the handoff contains or how the item is ranked.

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

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

A single tight sentence with no filler, and the essential concept is front-loaded. It reads as a fragment ('with its handoff') whose referent is unclear, which slightly undercuts crispness.

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 of describing the return value, and it only gestures at it ('the single next thing ... with its handoff'). An agent knows the flavor of the response but not its shape, so it is minimally adequate for a zero-param 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter guidance is needed.

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?

It conveys that the tool surfaces a prioritized next item plus a handoff, but the phrasing is abstract ('the single next thing that needs attention') rather than a clear verb+resource. With no output schema, an agent cannot pin down what object it actually returns or how it differs from siblings like forbiz_state or forbiz_get_action.

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 a faint implication of when to call it (when you need to know what to do next), but no explicit when/when-not and no routing to alternatives. Given ~19 siblings covering state, actions, and history, the absence of any differentiation is a real gap.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint, confirming it is a mutating POST call, but says nothing about whether the previous expected date is overwritten, what the reason is used for, or what the response 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?

A single front-loaded sentence with no waste; the action is stated before the endpoint parenthetical. Very terse, but nothing is padded.

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 only partial parameter documentation, the description leaves too much unstated: effect on existing signal state, role/auth requirements, and the purpose of reason. An agent has enough to guess a call but not to call it confidently.

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

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

Schema description coverage is only 33%; expectedSignalAt is documented in the schema but id and reason are not. The description gestures at the expected date but adds no meaning for the required id or the optional reason field, so it fails to compensate for the coverage gap.

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

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

States a specific verb (push/postpone) and resource (the date the signal is expected), plus the underlying endpoint POST /actions/{id}/postpone. It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as forbiz_close or forbiz_mark_executed.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the tool for rescheduling an expected signal rather than recording, claiming, or closing one.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value by disclosing the grouping taxonomy (needs_decision, needs_feedback, waiting, needs_review_date) and the timing.available_commands semantics, which tell the agent the response shape beyond what 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?

A single compact sentence front-loads the resource and its grouping, with the endpoint appended. The dotted 'timing.available_commands' notation is slightly cryptic, but nothing is wasted.

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

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

There is no output schema, so the description must carry the return-shape burden, and it does so by naming the groups and the timing/available_commands fields. It omits ordering or pagination behavior, but for a read-only queue view with full annotation coverage it is largely 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 100% for the single optional 'group' parameter, so baseline is 3. The description goes further by enumerating the concrete group values that the filter accepts, adding meaning beyond the schema's terse 'Only one group, e.g. needs_feedback'.

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

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

The description clearly conveys that this returns the full queue of pending items grouped by category, effectively a list/get of waiting work. The verb is implicit ("Everything waiting") rather than a crisp action word, and it does not explicitly contrast itself with siblings like forbiz_next, so it falls short of a 5.

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

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

Usage is only implied: an agent can infer that this is the tool to call for a complete view of the pending queue, versus forbiz_next for the next single item. There is no explicit when-to-use/when-not statement and no named alternatives, so it stays at the minimum-viable level.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so mutation and openness are covered structurally. The description adds genuinely new behavioral context: the signal is written once and corrections are new records, which tells the agent about immutability and the append-only model. It omits auth requirements and failure handling, keeping it from a 5.

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

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

Two short sentences, front-loaded with the core action and followed by the one behavioral caveat that matters. 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?

There is no output schema, so the description needn't explain return values, and annotations cover the mutation profile. But for a four-parameter tool with 25% schema coverage and a rich outcomeStatus enum, the description is too thin on parameter meaning and sibling routing to be fully complete.

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

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

Schema description coverage is only 25%, so the schema does not carry the load. The phrase 'what actually happened' loosely maps to actualSignal, but actionId, learningNote, and the outcomeStatus enum values (expected/partial/unexpected/deferred) get no explanation in the description, leaving four parameters largely 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?

States a specific verb (record) and resource (the signal / what happened after the action), plus the underlying endpoint POST /signals. It is clear on its own, but it never names or contrasts with the obvious sibling forbiz_check_signal or forbiz_mark_executed, so an agent must 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?

'Record what actually happened after the action' implies the moment to call it, and the write-once note hints at the correction workflow. However there is no explicit when-to-use versus check_signal, mark_executed, or close, and no stated prerequisites, leaving usage to inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, and the description usefully adds that capabilities are enforced server-side, which tells the agent it cannot exceed its permissions. It does not disclose error/response behavior, whether POST bodies are validated, or any reversibility concerns for arbitrary mutations, so it adds only moderate context 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 tool's identity, followed by the resource list, path-format example and the server-side enforcement note. Every sentence carries information and nothing is padded, though the parenthetical URL could be folded more tightly into the first sentence.

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 generic untyped HTTP passthrough with nested body/query objects and no output schema, the description is adequate: it names the spec URL, the route families and the path convention. It still leaves the agent without guidance on request shaping or expected responses, which matters more for an open-world escape hatch than for a narrow tool.

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

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

Schema description coverage is only 25% across 4 parameters, so the description must compensate, and it partially does by explaining that 'path' is relative to the API base and starting with '/', with concrete examples. It says nothing about how 'body' versus 'query' are used, nor when to choose GET versus POST beyond what the enum already shows, leaving half the burden unmet.

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

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

The description states a clear verb+resource: a generic escape hatch that calls any Forbiz Agent API route, and it enumerates the route domains (projects, decisions, delegations, outreach, policies, export, purchases) so the agent knows the surface area. The phrase 'any OTHER route' implicitly distinguishes it from the purpose-built siblings, but it never names one, leaving differentiation slightly inferential.

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?

'Escape hatch for any other route' clearly signals this is the fallback when no dedicated tool exists, and the pointer to the OpenAPI spec plus concrete path examples ('/projects', '/decisions/recommendation') tell the agent how to pick a route. There is no explicit statement of when NOT to use it or which sibling to prefer, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the HTTP method and the cross-tool 409 behavior, but says nothing about result shape, pagination, or result ordering for a broad search.

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 scope front-loaded in sentence one. The second sentence spends its words on a sibling tool's behavior rather than this tool, which is useful routing but slightly off-center.

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 search with annotations covering the safety profile and no output schema, the description covers scope, endpoint, and the key routing trap. It stops short of return-format or result-limit context, which an agent would otherwise want since 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 50%: 'q' is minimally described as 'Search terms' and the 'type' enum has no description at all. The prose enumeration of categories loosely maps to the enum values, giving some implicit help, but it never explains the 'type' filter (or values like 'all'/'context'), so it only partially compensates for the 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 (full-text search) and enumerates the exact resource set it spans (actions, evidence, people, organizations, projects, outreach, decisions), so an agent knows the search corpus without opening the schema. The endpoint (GET /search) further pins it down.

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 alternative for one case: resuming a commitment by key should go through forbiz_commit, and it explains the 409 signal. It does not distinguish this from content-specific siblings like forbiz_find_evidence or forbiz_get_action, so coverage of alternatives is partial rather than complete.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description goes well beyond them: the credential is stored locally, never displayed, and a second call is refused unless replace is true — side-effect and state semantics the annotations cannot express.

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

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

Three tight sentences, front-loaded with the action and endpoint, then credential handling, then return payload and the idempotency caveat. No filler and no repetition 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 still names the return shape (workspace, trial limits, claim link), covers auth/credential handling, and flags the re-invocation constraint. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds real meaning for replace by tying it to the refusal behavior ('it refuses unless replace is true'), making the parameter's purpose concrete in workflow terms, though agent_name and workspace_name are left 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?

States a specific verb and resource ('Open a provisional Forbiz workspace') plus the underlying endpoint (POST /bootstrap), which immediately distinguishes it from sibling lifecycle tools like forbiz_close or forbiz_claim_link. The 'provisional / no account, no email, no human' framing tells an agent exactly what kind of workspace is created.

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 says 'Call it once' and documents the refusal behavior when a credential already exists, with the condition that selects the alternative path (replace=true). That is real when-to-use and when-not-to-use guidance rather than an implied hint.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and reach are covered. The description adds the concrete payload contents (queues, counts, next priorities), which is useful, but says nothing about freshness, size, or access requirements.

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

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

A single front-loaded sentence that names the resource first and appends the endpoint as a parenthetical. No filler or redundant restatement of the tool name.

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

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

With no output schema, the description carries the burden of describing the return value; it gestures at the shape (queues, counts, next priorities) but not the structure of those fields. For a parameterless read tool this is adequate but thin.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema description coverage is 100% and no parameter guidance is needed.

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

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

States a clear resource (workspace overview) and enumerates the content: queues, counts and next priorities, with the underlying endpoint. It does not differentiate itself from siblings such as forbiz_next, which also deals with priorities.

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 when-to-use guidance is given. The mention of 'next priorities' actually overlaps with the sibling forbiz_next, and the description never clarifies which tool an agent should pick for that purpose or when a full state overview is preferable.

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