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

Annotations already disclose write, non-idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds only the domain framing of what counts as an account; it does not mention that names must be unique (only in the schema), what happens on duplicate names, or that creation is a prerequisite for other financial tools.

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 verb first and a parenthetical that earns its place by defining the resource's scope. Nothing extraneous and nothing buried.

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

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

For a simple three-parameter creation tool with full schema documentation and annotations, the definition is minimally adequate. It stops short of explaining the account's role in the broader financial model (transactions, transfers, balance reports), which is the main thing an agent would need beyond structured fields.

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% and each of the three parameters has its own description, including the uniqueness constraint and the balance minimum. The description adds no parameter-level meaning beyond that, 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 a specific verb and resource ("Create a capital account") and clarifies the resource with concrete examples (bank account, credit card, wallet), which distinguishes it from sibling add_transaction (a transaction, not an account). It does not explicitly contrast with list_accounts/remove_account, but the verb makes the distinction obvious.

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 agent can infer this is the creation step before adding transactions or transferring funds, but the description never says when to use it versus alternatives, nor any prerequisites (e.g. does a transaction require an existing account?). No exclusions or sequencing guidance.

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

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

Annotations already state readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the annotations, such as what happens on duplicate names, whether a category must exist before adding transactions, or permission 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?

The description is a single front-loaded sentence with no unnecessary wording. It is appropriately sized for a simple creation tool whose parameters are fully documented in the schema.

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

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

For a simple creation tool with complete schema coverage and useful annotations, the description is minimally adequate. It still omits practical context an agent might need, such as how category creation relates to sibling tools and what happens when a duplicate name is supplied.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description mentions the income/expense distinction, but this is already captured by the type enum and adds no meaning 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?

The description uses a clear verb-resource pair, "Create ... category," and specifies that the category type is income or expense. It distinguishes creation from sibling tools like list_categories and remove_category, though it does not explicitly name those alternatives.

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

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

The description gives no explicit when-to-use guidance, no prerequisites, and no comparison to alternatives such as list_categories or remove_category. Usage is only implied by the verb "Create."

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds nothing beyond that: it does not say whether duplicate contacts are allowed, what happens when is_primary is true and a primary already exists, what is returned (new contact ID), or whether missing optional fields can be filled later via update_contact.

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 action. The second sentence is definitional and mildly redundant with the first, but it does help an agent understand the resource type without cost.

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

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

For a 7-parameter mutation with no output schema, the description is thin: it omits the return value, duplicate handling, and the relationship to update_contact/remove_contact. It is enough to call the tool correctly given full schema coverage, but not enough to use it well within the contact lifecycle.

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

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

Schema description coverage is 100%, so every parameter including role, is_primary, and customer_id is documented in the schema. The description adds no parameter-level meaning such as format expectations or the interaction between is_primary and existing contacts, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Add a contact person to a customer organization") and clarifies what a contact is. It does not distinguish this from the closely related siblings update_contact, add_customer, or search_contacts, so an agent gets the action but not the boundary.

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

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

There is no guidance on when to use this instead of update_contact (for existing contacts) or when a contact should instead be captured via add_customer. No prerequisites, no mention that customer_id must reference an existing customer.

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 the generic write profile (not read-only, not idempotent, not destructive); the description adds the genuinely non-obvious fact that duplicate detection runs and can return a `conflict` payload with resolution options. It does not describe the successful return shape, but that is a modest gap for a create 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, front-loaded with the action, then domain framing, then the edge-case behavior. The middle sentence defining customers is mild padding but supplies useful domain context; nothing else 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?

For a 12-parameter mutation with no output schema, the description covers what is created and the one surprising response path (conflict + bypass). The remaining incompleteness is the success-response shape and where the new record's identifier comes from, which the agent cannot infer without an 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 description coverage is 100%, so the schema already documents all 12 fields including skip_duplicate_check. The description restates that flag's purpose in the retry context but adds no other field-level meaning, so 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?

Names a specific verb and resource ('Create a new customer record') and defines what a customer is, so the agent knows exactly what entity is produced. It does not explicitly differentiate itself from siblings like update_customer or add_contact, but the create semantics are 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?

Provides conditional guidance for the duplicate-conflict path ('If similar customers already exist...') and the retry procedure via skip_duplicate_check. It stops short of telling the agent when to reach for search_customers or update_customer instead, leaving the create-vs-update choice implied.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, and the description adds real context beyond them: what row is created, what default privileges are applied, and the owner-role authorization requirement. It stops short of stating what happens if the user is already a member, which matters given idempotentHint=false.

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 action and its side effect, followed by routing guidance and the authorization requirement. No redundant restatement of the tool name or title.

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

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

Covers the auth prerequisite, creation semantics, and defaults for a simple three-parameter mutation with no output schema. The only gap is the absence of any statement about the outcome when the user is already a member or what the caller receives on success.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the enum for financial_access and the FOUNDERS_OS_USER_ID matching constraint. The description reinforces the default privilege state but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Add a team member to the company") and immediately clarifies the side effect ("Creates their company_members row"). It explicitly distinguishes itself from siblings set_financial_access and set_member_owner, so an agent can route correctly without opening other schemas.

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

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

Explicitly names the two alternative tools and the conditions that select them (granting financial access, granting owner status), plus the prerequisite "Requires owner role." Minor friction: it says to use set_financial_access to grant financial access while the schema also exposes a financial_access parameter, leaving the agent to infer which path to prefer.

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

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

Annotations already declare this as a non-readonly, non-idempotent mutation, and the description adds meaningful behavior beyond them: external_action steps emit instructions for the AI to execute via connectors, while native_task steps create tasks in Founders OS. It does not warn about duplicate or re-run behavior, which leaves some mutation risk implicit.

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

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

Four sentences, front-loaded with the core action and step-type distinction, with no wasted wording. The append instruction is placed where an agent needs it when filling order_index.

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

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

Given 13 parameters, a nested params object, and no output schema, the description covers the essential model of step types, placeholders, and ordering. It could say more about the response or the relationship to sibling step-management tools, but the schema carries the per-field detail.

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

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

Schema coverage is 100%, so the schema already documents the 13 parameters. The description adds useful cross-parameter semantics: all text fields support {{placeholder}} syntax and the ordering model is driven by order_index.

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 ('Add an ordered step to a playbook') and immediately distinguishes the two step types, 'native_task' and 'external_action', so an agent knows exactly what the tool creates.

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

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

It gives clear operational guidance for appending steps via a higher order_index, but does not explicitly contrast this with update_playbook_step or remove_playbook_step, nor does it state prerequisites such as the playbook already existing.

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 idempotentHint=false, so the safety profile is covered. The description usefully adds that task status is left untouched, but it does not warn that repeated calls with the same note will create duplicate notes, which matters given idempotentHint=false.

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, the key constraint front-loaded, and no redundant restatement of the tool name or parameter list.

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 simple two-parameter mutation tool with full schema coverage and annotations that carry the safety profile; the description covers purpose and the main behavioral caveat. Only the duplicate-note consequence of non-idempotency is left unstated.

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

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

Schema description coverage is 100%, so task_id and note are already fully documented in the schema. The description adds no format, length, or content guidance beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource (add a note to a task) and adds a scoping clause, 'without changing its status,' which separates it from update_task and complete_task. It stops short of naming those siblings explicitly, 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?

Gives concrete usage contexts: logging updates, blockers, or partial progress mid-task. The status-isolation clause implicitly rules out using it for status transitions, but no alternative tool is named for those cases.

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

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

Annotations already establish that this is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely useful behavior beyond that: it discloses the side effect ('Automatically updates the account balance') and the sign-derivation rule. It does not warn that retries can duplicate entries despite idempotentHint=false, which is the main remaining gap.

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

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

Three short sentences, each carrying distinct information: what is recorded, the balance side effect, and the amount-sign rule. The most important constraints are front-loaded with no filler.

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

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

For an 8-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, side effect, and the trickiest input rule. It leaves out duplicate/retry behavior and whether the account balance update is transactional with the insert, which would round it out.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the positive-amount and sign-derived-from-category rules. The description's 'Provide a positive amount' restates the schema rather than adding new meaning. A 3 baseline is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Record an income or expense transaction.' This clearly separates the tool from list_transactions, remove_transaction, and transfer_between_accounts in the sibling set. It does not explicitly name an alternative, so it stops short of a 5.

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

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

Usage is implied by 'Record an income or expense transaction' and by the note that the account balance is updated automatically, but there is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent when to prefer transfer_between_accounts or how to handle an already-recorded transaction (remove vs re-add).

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

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

Goes well beyond annotations by disclosing the key semantic trait: exactly one assignee, so assigning replaces rather than adds. It also documents the personal-task constraint and, critically, the failure mode – a `conflict` field means the task was NOT assigned and must be retried with a resolution. That is exactly the kind of post-call behavior an agent needs.

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

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

Front-loaded with the core action and the single-owner rule, then the value formats, then the conflict-handling note. Dense but each sentence carries information; the parenthesis idiom ('one neck to grab') is mildly expendable but clarifies intent.

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 compensates by explaining the `conflict` response field and the retry path. Combined with the personal-task rule and the required resolution parameter, an agent has everything needed to call and recover correctly.

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

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

Schema coverage is already 100%, but the description still adds real meaning: accepted value forms (user ID, '@claude'/'@gpt', empty string), what empty string means (unassign), and the personal-task restriction on assigned_to. Adds value over the schema rather than restating it.

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 ('Assign or reassign') and resource ('a task to a team member or AI agent'), and immediately distinguishes this from a mere field update by explaining that assignment replaces the single accountable owner. An agent can tell this apart from update_task, create_task, or link_task without opening a schema.

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

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

Gives concrete when-to-use guidance: how to specify human vs AI vs unassign, what to do for additional involved people (@person tags or description text), and the personal-task restriction. It stops short of explicitly naming sibling tools like update_task as the alternative for editing other fields, so not a full 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 declare a non-read-only, non-idempotent, non-destructive write. The description usefully adds that content is snapshotted and outlives the cache, which is real behavior beyond the annotations. However, given idempotentHint=false, it never warns that repeated calls likely create duplicate bookmarks or state 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?

Three short sentences, front-loaded with purpose, then mechanism, then parameter sourcing. The final sentence duplicates schema text, which is the only wasted line but is small enough not to hurt readability.

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

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

For a two-parameter write with no output schema and full annotation coverage, the description covers the essential workflow and persistence semantics. It stops short of describing the return value (bookmark identifier or confirmation) and duplicate handling, which an agent would need to chain calls correctly.

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

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

Schema coverage is 100% and both parameters are fully documented, including the 1-based indexing and the get_feed_items origin. The description's sentence about feed_url and item index largely restates the schema, so it adds little beyond the 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 and resource ("Save a feed item for later") and adds the mechanism ("Snapshots the item content so it persists beyond the cache"), which makes the effect concrete. It does not distinguish itself from neighbors like read_feed_item, list_bookmarks, or remove_bookmark, so an agent must infer the contrast rather than read it.

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

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

"Save a feed item for later" implies the use case, and the reference to get_feed_items establishes the ordering dependency (fetch items, then bookmark one). There is no guidance on when NOT to use it, e.g. re-bookmarking an already-bookmarked item or reading instead of saving, so usage is implied rather than stated.

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

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

Goes well beyond the annotations by disclosing what is returned (ordered procedure, exact memory call, previous checkpoint for continuity) and that the tool itself performs no writes while the agent executes the steps. That clarification is valuable given readOnlyHint=false, though the surface tension between 'does not write anything itself' and a non-read-only hint is left for the agent to reconcile rather than resolved explicitly. No rate limits, error modes, or side effects of the downstream writes are described.

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 trigger phrases and the identity as a bookend, then moves to return contents and the no-write caveat. Efficient overall, but the closing sentence about the project tag repeats the schema's own wording and could be trimmed.

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

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

There is no output schema, and the description compensates by enumerating the returned artifacts (procedure steps, memory call, previous checkpoint) and the sequence of actions the agent must take. For a zero-required-parameter orchestration tool, an agent has everything needed to call it and act on 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 100% and the schema already explains all four parameters, including the project tag and the 'ask the user if unknown' rule, so the description largely restates structured data. It adds only marginal meaning, mainly reinforcing why the project tag matters (loading the previous checkpoint) and noting the storing step happens after project confirmation. Baseline 3 is appropriate when the schema carries the parameter burden.

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 role (end-of-session bookend to get_session_start) and a concrete deliverable (the ordered checkpoint procedure plus the exact memory call and prior checkpoint). The verb/resource pairing is unambiguous and distinguishes it from get_last_checkpoint and get_session_start by naming the counterpart directly.

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

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

Gives explicit invocation triggers ('checkpoint', 'let's checkpoint', 'wrap up this session') and states the prerequisite behavior when the project tag is missing ('ask the user which project before storing'). The alternative, get_session_start, is identified as the paired bookend, so the agent knows which of the two to call at each end of a session.

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 establish that this is a non-destructive, idempotent write; the description adds substantive behavior beyond that — the conflict on an incomplete blocker, the unblocked_tasks side effect, and the scoping rule for persisted memories. Its weakness is that the force guidance is stale relative to the schema's deprecation note, which could steer an agent wrong.

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

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

Front-loaded with the core action, then layered side effects and edge cases in descending priority; almost no filler. The closing force sentence is the one element that does not earn its place, since it duplicates and contradicts the schema's deprecation note.

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

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

With no output schema, the description usefully covers the return surface — unblocked_tasks and the conflict payload — which an agent otherwise could not anticipate. It falls short only on the resolution/force discrepancy, leaving the correct recovery path ambiguous.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all six parameters including the confirm/cancel enum. The description reinforces store_as_memory and the conflict flow, but its only parameter-directive sentence endorses the deprecated force flag and never explains the enum it implies.

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

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

Opens with a specific verb+resource ("Mark a task as done") that is unambiguously distinct from siblings like update_task, remove_task, and add_task_note. The follow-on sentences about memory persistence and dependency unblocking further pin down what state change occurs.

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

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

It gives a real branching rule for the blocked case (conflict response, then complete anyway), which is the main decision point. But it never says when to prefer this over status-change siblings such as update_task, and it points agents at force=true without mentioning the preferred resolution:"confirm" path.

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, idempotentHint=false, and openWorldHint=false, so the agent knows this is a non-destructive, local, non-idempotent write. The description adds useful context that the created object is an empty container to be populated later. It does not disclose that slug uniqueness is enforced per company (a likely failure mode) or what the caller receives on success, both of which would be valuable for a mutation tool.

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

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

Two short sentences with zero redundancy: the second defines the object before the agent must reason about it, and the third gives the follow-up action. Front-loaded with the action and nothing an agent must skip past.

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 three-parameter create tool with full schema coverage and adequate annotations, the description covers what the object is and how to continue building it. The remaining gap is that no output schema exists, so the agent has no way to know whether the response returns the new playbook's id (needed to call add_playbook_step), and the uniqueness-failure behavior is unmentioned.

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%, with each of the three properties documented including examples and the slug uniqueness constraint, so the description need not repeat them. The description adds no parameter-level meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Create a new reusable playbook template") and defines the domain object as "an ordered set of steps run against a customer to automate project setup," which an agent could not infer from the name alone. The verb clearly separates it from update_playbook, remove_playbook, and list_playbooks, though those siblings are never named.

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 closing sentence gives a concrete workflow cue ("Add steps with add_playbook_step after creation"), which tells the agent this is step one of a multi-call sequence. However, there is no guidance on when a playbook is the right structure versus creating tasks or projects directly, and no exclusion conditions or prerequisites.

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

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

Annotations already declare the mutation/duplicate-sensitive profile (readOnly=false, idempotent=false). The description adds real value beyond that: the tag-registry side effect and the conflict-on-duplicate-slug behavior, neither of which is derivable from schema or annotations. It stops short of describing permissions or what the returned object contains.

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

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

Front-loaded with the action and side effect, then error behavior, then usage guidance, then the confirmation rule. The list of example triggers is slightly padded but each clause carries navigational value.

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 3-parameter mutation with no output schema, the description covers the primary action, side effects, failure mode, and usage guardrails. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level guidance and introduces a 'slug' concept that is not a parameter, leaving the agent to infer that slug is derived from name.

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

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

Opens with a specific verb+resource ("Register a new project") and immediately discloses the side effect of auto-creating a #-prefixed tag. It does not explicitly distinguish itself from siblings like update_project or list_projects, but the creation framing makes the distinction obvious.

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

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

Gives explicit trigger conditions with quoted example utterances, states the proactive-suggestion case (user mentions a project not in the registry), and adds a gating rule ("Always confirm before creating"). This is as close to unambiguous routing as a description gets.

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, idempotentHint=false and a closed-world scope, so the description only needs to add context. It does: it discloses a failure mode ('Returns an error if a tag with the same slug already exists') and the uniqueness constraint that is not derivable from annotations, which directly explains the non-idempotent hint.

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: purpose first, then the constraint, then the error behavior. Minor redundancy in 'tag ... in the tag registry', but nothing that costs the agent comprehension.

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 create tool with full schema coverage and a defined annotation profile, the description covers what the tool does, the uniqueness rule, and duplicate handling. The only gap is the success return shape (no output schema, and nothing says what a created tag looks like), which is a small omission for a tool this simple.

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

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

Schema description coverage is 100%, so all four parameters (name, color, scope, description) are already documented, and the enum/default for scope is in the schema. The description's only extra semantic content is that the slug is a lowercase hyphenated derivative of the name rather than a supplied parameter — a modest but real addition.

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

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

The description opens with a specific verb and resource ('Register a new tag in the tag registry'), which is unambiguous against siblings like list_tags, rename_tag, remove_tag, and preview_tags. An agent can tell this is the creation path without opening the schema.

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

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

Usage is only implied by the verb 'Register' — the description never states when to create versus rename an existing tag or how this relates to preview_tags/list_tags. It does supply one genuine precondition (slug uniqueness per company), which helps, but there is no explicit when/when-not guidance.

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

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

Annotations already cover the read/write, idempotency, and open-world profile, but the description adds genuinely new behavior: visibility semantics per scope, the fact that a `conflict` field means the task was NOT created, and the single-assignee design rationale. The final retry sentence is muddled — it talks about 'the selected date' in a paragraph that began with an assignment conflict, leaving the recovery path ambiguous.

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

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

The first three sentences are tight and front-loaded, but the closing conflict/retry instruction is compressed to the point of confusion and mixes an assignment conflict with a due-date retry. That single sentence is doing too much work and is the least parseable part of an otherwise efficient description.

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

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

For a 13-parameter mutation tool with no output schema, the definition covers the critical decisions: scope visibility, assignment format, entity linking, and failure signaling. It leaves out what a successful response looks like and does not tie resolution='make_org'/'cancel' to the conflict-detection instructions, which an agent will need to connect on its own.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining what scope visibility actually implies for teammates and by justifying why assigned_to accepts exactly one owner rather than a list. It does not clarify how resolution interacts with the returned conflict payload, which is the one parameter pairing where intent could be misread.

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

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

Opens with a specific verb+resource ('Create a new task') and immediately differentiates the tool's main axis of variation (org vs personal scope). An agent can distinguish it from update_task, assign_task, and complete_task without opening any schema.

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

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

Gives clear in-context guidance: default scope is org, personal tasks restrict assignment, and links can be attached at creation time. It also routes the agent through a conflict path (do not assume creation succeeded; ask the user, then retry). The gap is that it never explicitly says when to prefer create_task over sibling flows like create_playbook or when to use assign_task afterward rather than assigned_to.

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, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds genuinely new behavioral facts: the log is immutable, records cannot be modified or deleted, and visibility is permission-gated. It omits ordering/pagination behavior for a potentially large result set.

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 resource and the access rule. The domain list is somewhat duplicative of the domain parameter's enum description, but it still serves the purpose of telling the agent what kinds of events exist.

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, zero-required read tool with full schema coverage and annotations present, the description covers access model, scope, and content domains well. The remaining gap is return-value shape — there is no output schema, so the agent learns nothing about the fields of an audit entry or result ordering.

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%, with detailed per-parameter descriptions including enum meanings and date formats, so the baseline is 3. The description restates the scope semantics ('all' = owner-only, 'mine' = any member) and maps domains, but adds no filtering semantics beyond what the schema already documents.

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 immutable audit log for this company') and immediately scopes it by role. No sibling tool offers audit history, and the enumeration of covered domains (financial, CRM, memory, playbooks, access, members) makes the resource boundary unmistakable.

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

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

Gives explicit role-based routing: owners use scope='all', any member uses scope='mine'. The description clarifies when to use this tool versus the deletion/history siblings. It does not name alternative tools for narrower lookups (e.g. list_deleted, get_project_history), so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing that the result is an aggregate including contacts, recent interactions, and open tasks — a trait not visible in the schema. It does not define how far back 'recent' reaches or what happens when the customer is not found, leaving those behaviors opaque for a tool with no output 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?

One sentence, front-loaded with the verb and resource, with the payload contents following immediately. Every clause carries information and there is no filler or 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?

For a single-parameter read tool with full annotation coverage and full schema coverage, the description supplies the one thing structured data cannot: what the response contains. The remaining gap is minor — undefined recency windows and no not-found behavior — but not enough to prevent 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 coverage is 100% and the single parameter is documented in the schema as 'Customer UUID' with a uuid format. The description adds no further meaning about the identifier (e.g., where to obtain it or whether it accepts external IDs), so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Get a single customer') and the word 'single' implicitly contrasts with the list_customers and search_customers siblings. It stops short of naming those siblings explicitly, so an agent must infer the distinction rather than being routed to the right tool directly.

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

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

Usage is only implied: 'a single customer' suggests a known customer_id lookup rather than a browse/search operation, which is consistent with the required UUID parameter. There is no explicit statement of when to prefer this over search_customers or list_customers, and no guidance on what to do when the ID is unknown.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description's added value is the disclosure that the response carries a 'render' field with tiered rendering guidance that must be consulted before replying — non-obvious information with no output schema to convey it. It stops short of describing the shape or size of the summary payload.

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 resource and its contents, followed by the actionable caveat about the render field. 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 does the necessary work of summarizing the returned sections and flagging the render-field obligation. It leaves ambiguity around what 'phase' means and how the tiering behaves, but nothing required to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description restates the 7/14/30-day window and usefully scopes it to 'upcoming tasks', but adds no format or timezone detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Get a CRM dashboard summary') and then enumerates the exact contents: customers by type and phase, overdue tasks, recent interactions, upcoming tasks. That content list also differentiates it from siblings like get_task_summary and get_financial_summary without needing to name 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?

The only directive is 'check [the render field] before composing your reply', which concerns post-call behavior rather than when to choose this tool. There is no explicit guidance on when to prefer it over get_task_summary, get_financial_summary, or get_entity_card, so usage is only implied by the content 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description usefully adds that this is a fan-out/aggregate read spanning four data classes, but says nothing about how many tasks or interactions are returned, any caps, or cost relative to the individual calls it replaces.

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, both earning their place: the first front-loads what is returned, the second front-loads when to reach for it. No filler, no restatement of the name or title.

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

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

With no output schema, the description correctly carries the burden of sketching the return contents at a high level, which it does. It is nearly complete for a two-parameter read tool, with minor gaps around result limits and the fact that the entity types are restricted.

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%: both parameters are documented and entity_type carries an enum, so the baseline is 3. The description adds no meaning beyond the schema — it never explains that entity_type must be one of the three types or how the response shape differs by type.

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

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

The description names a specific verb and resource ("Get a complete picture of any entity") and enumerates exactly what the composite response contains: the record, open tasks, recent interactions, and linked transactions. Sibling differentiation is only generic ("Replaces multiple separate calls") rather than naming get_customer, list_entity_tasks, list_interactions, or list_transactions, and "any entity" slightly overstates scope versus the customer/contact/transaction enum.

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 context is stated concretely with the motivating question "what's going on with X?", which tells an agent this is the aggregate-context tool rather than a single-record fetch. It also hints at the alternative pattern (multiple separate calls). It stops short of naming when NOT to use it — e.g., when only the raw record is needed, get_customer is cheaper.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: output shape (one headline per tag, 8 cap), source restriction (pinned only), and a directive to read the 'render' field for tiered rendering guidance before replying. It stops short of describing behavior with zero pinned feeds or truncation semantics.

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

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

Five short sentences, each carrying distinct information—purpose, output shape, integration role, source scope, and a pre-composition instruction—with the essential scope constraint front-loaded and no filler.

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

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

With no output schema, the description does the work of describing the return ('one headline per tag, capped at 8' plus a 'render' field), which is sufficient for an agent to use the result; minor gaps remain around empty-state and error 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?

Schema coverage is 100% with a single optional parameter, so the schema already documents max_headlines and its default. The description's 'capped at 8 total' is consistent but adds nothing about the number-or-string union type or how strings are parsed, so baseline 3 applies.

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

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

States a specific verb and resource ('Generate a compact headline briefing from pinned feeds') plus scope ('Only fetches pinned feeds') and output shape ('one headline per tag, capped at 8'), which clearly separates it from siblings like get_feed_items and get_dashboard.

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

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

Gives clear context for use ('for the morning dashboard', 'Designed to be included in get_session_start without slowing it down') and a scope constraint (pinned feeds only), but never names an explicit alternative such as get_feed_items for full unpinned content, leaving the when-not choice 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, idempotentHint, and destructiveHint=false, so safety is covered; the description adds real value by disclosing the return shape (a numbered summary list with title, author, date, and content-availability flag) and the fact that items are numbered specifically so they can be passed to read_feed_item. It leaves ordering/freshness and limit behavior implicit, which keeps it short of a 5.

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

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

Four short sentences, front-loaded with purpose and return shape before the hand-off instruction and filters; almost every sentence earns its place. The final filter sentence is somewhat redundant with the schema descriptions, costing it a point.

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

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

With no output schema, the description correctly spends words on what comes back and how to consume it (numbered summaries → read_feed_item). For a zero-required-parameter read tool with fully documented params and clear annotations, nothing essential is missing.

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

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

Schema coverage is 100%, so all three parameters already carry descriptions, and the description largely restates them (feed_id for a specific feed, tag for a topic) without adding format, default, or semantics beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('Fetch the latest items from subscribed feeds') and immediately scopes it by contrast: this returns summaries, while read_feed_item returns full content. An agent can distinguish it from siblings like list_feeds or get_feed_briefing without opening any schema.

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

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

It explicitly routes the agent to the correct follow-up tool ('Use read_feed_item with the item number to get full content') and explains the two filtering modes (feed_id for one feed, tag for a topic). It does not mention when to prefer list_feeds or refresh_feeds instead, so there is no complete exclusion set, but the primary usage path 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, idempotentHint, and no destructiveness, so the safety profile is covered. The description adds the important non-obvious behavior beyond that: an ownership-based authorization rule governing whose access level can be read, which the agent could not infer from 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?

Three short sentences with the core action front-loaded and the permission rules following immediately; nothing is redundant or padded. It could have been tightened into two sentences, but there is no wasted content.

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-only tool with full schema coverage and no output schema, the description supplies the action, the default behavior, and the authorization model. Only the failure behavior for unauthorized cross-user checks is unstated, which is a minor omission at this complexity level.

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% and the single parameter already states "Omit to check your own access level," so the schema carries the parameter semantics. The description restates the authorization meaning of target_user_id but adds no format or validation detail beyond the schema, making 3 the appropriate 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?

"Check a user's financial access level" gives a specific verb (check) and resource (financial access level), which cleanly separates it from the sibling set_financial_access (which mutates that level). It does not explicitly name the sibling, so the differentiation is implied by the read-only wording 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 description gives clear conditional guidance: omit target_user_id to check your own access, or be an owner and pass target_user_id to check someone else. It states the permission condition that selects each mode, though it does not say what happens if a non-owner supplies a target_user_id (error vs. denial), leaving one 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral information that the structured fields do not carry: the response contains a 'render' field with tiered rendering guidance that should be consulted before replying — a non-obvious output contract worth flagging, especially since no output schema exists. It stops short of describing the shape of the asset/income/expense values themselves.

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, both front-loaded with the highest-value fact first: what the snapshot contains, then the render-field contract. No filler, no restatement of the title, nothing that could be cut without losing information.

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

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

For a zero-required-parameter read tool with no output schema, the description covers what is returned at a useful level and warns about the render field. The remaining gap is access scoping — sibling tools set_financial_access and get_financial_access imply the result may be permission-limited, and the description says nothing about what happens when financial access is unset.

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% and the single optional 'timezone' parameter is fully documented in the schema, including that it shifts ytdStart. The description's phrase 'year-to-date' hints at the same concept but adds no syntax, format, or default behavior beyond the schema, 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 a specific verb ('Return a snapshot') and resource ('company's financial position') and enumerates the components: total assets across all accounts, year-to-date income and expenses. That content list implicitly separates it from siblings like get_pl_report or list_accounts, but it never names an alternative explicitly, so the differentiation is inferential rather than stated.

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

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

There is no when-to-use guidance, no exclusion, and no reference to the obvious neighbor tools (get_pl_report, list_accounts, list_transactions) that overlap this data. The only directive — 'check it before composing your reply' — governs output handling, not tool selection, so the agent must guess whether a summary or a detailed report is the right call.

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

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

Annotations already establish this as a safe read-only, idempotent lookup. The description adds useful behavior beyond them: resume with an ambiguous target returns a disambiguation conflict rather than guessing, and the response includes a render field that should be checked before replying. It does not describe pagination or ranking details, but the key behavioral traits are covered.

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

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

The description is dense but front-loaded and organized around purpose, triggers, parameter rules, intent behavior, and response handling. It is somewhat long and repeats schema guidance, but every sentence provides actionable context.

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-optional-parameter lookup tool with no output schema, the description covers when to call it, how to scope project and author, how intent changes behavior, and what to do with the response's render field. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, and the description largely repeats the schema's parameter guidance for project, author, and intent rather than adding new syntax or constraints. Baseline 3 is appropriate when the schema already carries the parameter semantics.

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

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

The description begins with a specific verb and resource: 'Retrieve the caller's most recent checkpoint to show it or resume from it.' It clearly distinguishes this read/lookup tool from a checkpoint-creation sibling by focusing on retrieval and explicitly naming the two supported intents.

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

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

It gives explicit trigger phrases ('what was my last checkpoint', 'show me where I left off', 'pick up from my last checkpoint') and clear rules for the tricky project and author parameters, including when to omit project and when to use author='anyone'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the response includes the ordered step list and connector requirements, which is useful shape information in the absence of an output schema, but says nothing about error behavior for missing or invalid playbook IDs.

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, no filler, with the return contents front-loaded and the usage note second. Every clause carries information an agent needs.

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

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

For a simple one-parameter read tool with rich annotations and no output schema, the description covers what is returned and when to reach for it. Only minor gaps remain: behavior on a nonexistent playbook and how connector requirements are represented.

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 and schema description coverage is 100%, with the schema itself noting 'Playbook UUID or slug.' The description adds no additional meaning about the identifier format or resolution rules, so the schema does the heavy lifting.

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

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

States a specific verb (fetch) and resource (a single playbook) plus what is returned: the full ordered step list and connector requirements. The word 'single' implicitly distinguishes it from list_playbooks, though no sibling is named explicitly.

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

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

Gives a clear trigger: 'Use before running to inspect what the playbook will do and which connectors it needs,' which points to the run_playbook workflow. It lacks explicit exclusions (e.g., use list_playbooks when you don't have an ID), so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered structurally. The description adds what the call returns (execution log and status), which is mild extra context but nothing about behavior for missing/unknown run IDs or retention.

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

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

One front-loaded sentence with no filler. It is efficient but so terse that the verb 'Fetch' carries nearly all of the semantic load.

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 must convey what comes back, and it does so minimally ('execution log and status'). For a one-parameter read tool that is adequate, but it leaves the shape of the log and status undefined.

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% and the single run_id parameter is already documented as a playbook run UUID. The description adds no meaning beyond the schema, 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 a specific verb (Fetch) and resource (execution log and status of a playbook run), and the word "specific" distinguishes it from the sibling list_playbook_runs, which returns many runs. It does not explicitly name that sibling, keeping it 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: 'a specific playbook run' suggests it is the single-run counterpart to list_playbook_runs, but no condition, prerequisite, or alternative is stated. An agent can infer the routing but is not told it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral detail beyond that: transactions flagged exclude_from_reports are omitted, and unattributed transactions are bucketed as 'Unattributed' in the rollup. Missing is any note on aggregation semantics (e.g., how refunds or transfers are treated), which would have pushed this higher.

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 operation, then optional modes, then an edge case, then a response-handling instruction. Every sentence carries information; the only mild redundancy is the Unattributed rule appearing both here and in the schema.

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

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

There is no output schema, so the description usefully discloses that the response contains a render field with tiered rendering guidance — an important instruction the agent could not otherwise know. Combined with the exclusion rule and rollup semantics, this covers what an agent needs for a read-only reporting tool, though aggregation edge cases remain unstated.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description earns a bump by explaining the interaction between the optional parameters rather than merely restating them — `group_by_customer` produces a rollup 'alongside the category breakdown' while `customer_id` restricts the whole report. The Unattributed bucketing is repeated from the schema, which limits the added value.

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

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

States a specific verb and resource ('Return a profit & loss summary grouped by category') plus the scoping dimension (date range), which is enough for an agent to distinguish it from generic summary tools. It stops short of naming the closest sibling (get_financial_summary) or explaining how the two differ, so differentiation is inferred rather than explicit.

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

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

Gives concrete selection guidance for the two optional parameters: use `customer_id` to scope to one attributed customer, or `group_by_customer: true` to get a per-customer rollup alongside the category breakdown. It also instructs the agent to check the render field before replying, which is actionable context. It does not state when to prefer this over get_financial_summary or when not to use it 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavior beyond that: results are grouped by status and only "recent items shown," which warns the agent that the task list may be truncated rather than exhaustive. It stops short of quantifying that truncation or describing ordering rules.

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

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

One sentence, front-loaded with the verb and the object, followed by the concrete contents of the response. There is no filler, hedging, or 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 carries the return-value burden and does so by naming the three payload parts and the grouping/recency behavior. A minor gap remains: "recent items shown" is unquantified, and non-fatal cases (e.g., a project with no tag or no tasks) are not described, though annotations cover the safety profile.

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

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

Schema coverage is 100% with a single required parameter (project_id, UUID, format-annotated), so the schema already carries the full parameter burden. The description adds nothing about the identifier beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Get a full project card") and enumerates the payload: project details, associated tag, and all tasks/customers carrying the tag. That is more informative than a bare name restatement, but it never distinguishes itself from close siblings like get_project_history, get_entity_card, or list_projects, 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?

Usage is only implied: the phrase "full project card" suggests fetching everything about one project, which implies it is the tool for a single-project deep look rather than list_projects. There is no explicit when-to-use, no mention of get_project_history as the alternative for historical data, and no prerequisites (e.g., a valid project must exist).

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

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

Annotations already establish this as a safe, idempotent, read-only, closed-world operation, so the description's additions sit on top of that: default filtering to checkpoint entries, newest-first ordering, and a render field with tiered rendering guidance that the agent should consult before replying. That last detail is genuinely useful behavioral context not present in the schema or annotations, though nothing is said about empty results or how deep the default limit reaches.

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

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

Front-loaded with the core concept, then use cases, then the discriminator against memory_recall, then defaults and response guidance. Every sentence has a job, with only mild redundancy in re-specifying the checkpoint default that the schema already states.

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

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

For a seven-parameter read tool with no output schema, the description covers purpose, default narrowing, ordering, and a pointer to the render field in the response. Combined with a fully documented schema, an agent has enough to call it correctly; only edge-case behavior (empty history, limit interplay) is unaddressed.

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% and every parameter carries its own description, including defaults for kind, limit, scope, and author. The description only restates the kind default and the 'all' escape hatch, which the schema already documents at more length, so it adds little semantic value beyond the schema 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?

Names a specific resource and shape: a chronological timeline of stored memories for a single project. It explicitly separates itself from memory_recall by calling itself the 'chronological companion,' which is semantic and ranked, so an agent can pick between the two 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?

Gives concrete when-to-use cases ('where did we leave off', assembling a project narrative) and names the alternative tool plus the axis that distinguishes it (chronological vs semantic/ranked). The kind='all' instruction tells the agent how to widen scope when the default is too narrow.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is a pointer rather than a fetcher, and it carries the session-scoped rendering_contract that governs all later founders-os output. However, the two closing sentences about rendering_contract and the render field overlap heavily rather than adding distinct disclosure.

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

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

The definition is front-loaded with the core pointer semantics before the usage triggers and contract notes. The last sentence substantially restates the rendering_contract sentence before it, which is the one clear piece of waste in an otherwise tight description.

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

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

There is no output schema, and the description compensates by naming what comes back: the date, a parallel tool list, rendering_contract and render fields. Combined with full schema coverage and a complete annotation set, an agent has everything needed to call this correctly at session start.

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

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

Schema description coverage is 100%, so timezone, client_capabilities and expected_contract_version are already fully documented in the schema, including enum values and defaults. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description states a specific role (session orientation pointer) and precisely what is returned: today's date plus a list of tools to call in parallel. It also explicitly negates a plausible misreading with 'Does not fetch data itself', which separates it cleanly from every data-fetching sibling such as get_feed_briefing or get_dashboard.

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 pinned to concrete triggers: 'at the start of every session' and user phrasings like 'start my day' or 'catch me up'. It lacks an explicit when-not clause or a named alternative, but with no comparable orientation tool among the siblings there is little ambiguity to resolve.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's contribution is the return shape: each row carries days_stale and a suggested triage action, and the response embeds a render field with tiered rendering guidance the agent should read first. That is genuine behavioral context beyond the annotations, though it omits result volume, ordering, and any cap.

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, zero filler, with the core purpose front-loaded and the qualifying criteria immediately after. The closing render-field instruction earns its place because no output schema exists to convey 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?

With no output schema, the description carries the return-value burden and does so reasonably by naming the row fields and the embedded render guidance. It stops short of describing result limits, sorting, or what an empty list means, which leaves a small gap for an agent planning its reply.

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

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

Schema coverage is 100%, so scope, timezone, and max_age_days are already fully documented in the schema. The description's 'N days' phrasing loosely echoes max_age_days but adds no format, default, or interaction detail beyond what structured fields provide, so baseline 3 applies.

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

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

States a specific verb and resource ('Surface stuck, stale, and overdue tasks') and then enumerates the exact qualifying conditions: in_progress untouched for N days, blocked, and overdue todo/in_progress. This distinguishes it from the plain list_tasks/get_task_summary siblings without needing to open any schema.

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

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

The triage framing implies the context ('that need triage') and the render-field note implies a conversational workflow, but it never explicitly says when to reach for this versus list_tasks, list_entity_tasks, or get_task_summary, nor does it state any exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds the meaningful payload detail that linked entities and notes are included, which implies a potentially large response. It says nothing about behavior for an unknown/invalid ID or about response size, so it is an incremental rather than rich contribution.

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

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

One sentence, front-loaded with the verb and resource, with the notable payload scope ('including all linked entities and notes') placed at the end. 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 does the necessary work by telling the agent what comes back (task plus linked entities and notes). Given the absence of an output schema, a brief note on error behavior for an unknown ID would have completed it.

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

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

There is a single parameter with 100% schema coverage (task_id documented as 'Task UUID' with uuid format), so the schema carries the semantics. The description's 'by ID' restates the schema rather than adding format or origin details, making the baseline 3 appropriate.

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 ('Fetch a single task') and the lookup key ('by ID'), which clearly separates it from list_tasks and create_task. It does not explicitly differentiate itself from get_task_summary or get_entity_card, so an agent must infer that this is the full-detail fetch.

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 usage (you need a task ID to retrieve one task in full), but never states when to prefer it over get_task_summary, list_tasks, or list_entity_tasks. No exclusions or prerequisites are given, leaving routing to inference from the name.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. Beyond that, the description discloses a non-obvious response trait: the payload carries a render field with tiered rendering guidance that the agent should consult before replying — genuinely useful behavioral context the schema does not reveal. It does not discuss aggregation cost, data freshness, or empty-state behavior.

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

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

Three tight sentences, no redundancy: the content inventory comes first, then the usage trigger, then the response-handling instruction. Each sentence carries distinct information an agent would otherwise have to guess.

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 takes on the job of describing the return value, and it does so by enumerating the summary sections plus the render field. Between that and the fully documented three-parameter schema, an agent has enough to call it correctly. Minor gaps remain around empty-queue behavior and response size.

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%, and the schema already explains the days enum, the scope enum, and the timezone rationale (off-by-one protection after ~7pm UTC). The description contributes no additional parameter meaning, which is acceptable given the schema carries the load — the baseline 3 applies.

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

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

The description names a specific artifact — a dashboard-style summary of the task queue — and enumerates its sections (overdue, due today, upcoming, counts by status/assignee, AI tasks for @-prefixed agents). That content breakdown lets an agent distinguish it from the plain listing siblings like list_tasks or list_entity_tasks without opening a schema. It stops short of naming the alternative tools explicitly, so it falls just 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?

"Call at session start to orient on what needs attention" gives a concrete trigger, and the closing sentence prescribes a follow-up behavior (check the render field before composing a reply). There are no explicit exclusions, e.g. it never says when to prefer list_tasks or get_dashboard instead, so the routing guidance is directional 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 already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value by disclosing the breadth and content of the returned guide, which is the main unknown for a no-parameter tool; it does not state size, format or whether the guide is static documentation.

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 what is returned, followed by the usage trigger. Nothing is redundant, and the domain enumeration is compact rather than 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 zero-parameter tool with no output schema and full annotation coverage, the description supplies the key missing information: the contents of the guide. The only gap is its relationship to sibling orientation tools such as show_capabilities and get_session_start.

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 no parameter semantics to explain and the baseline of 4 applies. The description correctly implies it is called with no arguments.

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

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

The description names a specific verb and resource ('Returns a detailed guide on how to use Founders OS') and enumerates the six domains plus surface tools, search protocols, workflows and tips, so the agent knows exactly what comes back. It stops short of distinguishing this from the related sibling show_capabilities, which likely overlaps in purpose.

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

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

'Call this when uncertain about how to approach a task' gives an explicit, actionable trigger condition rather than leaving usage implied. It does not name exclusions or point to alternatives such as get_session_start or show_capabilities when those might be the better first call.

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

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

The annotations declare openWorldHint=false, but the description says the tool can 'query the registry for the latest version' and reports the 'published head of that channel' — external network behavior. This contradicts the annotation. Otherwise the description is behaviorally rich, but the contradiction forces a 1.

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 content is front-loaded and every clause conveys useful information, but it is packed into two very long, dense sentences with multiple statuses and conditional instructions. It is informative but hard to scan; structured bullets would improve 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: semver-aware and channel-aware comparison logic, versionStatus values, updateAvailable semantics, dbSchemaStatus values, and follow-up relay instructions. Nothing essential is missing for correct interpretation.

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

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

There is only one parameter, check_latest, and schema description coverage is 100%; the schema already documents it with its default. The description does not add meaning beyond the schema for this parameter, so baseline 3 applies.

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

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

The description states a precise verb and resource ('Returns the running version of @ourthinktank/founders-os') and enumerates the exact diagnostic fields returned: rendering contract version, launchMethod, channel, channel head, dbSchemaStatus, versionStatus, and updateAvailable. No sibling tool covers this same package/version/schema-drift scope, so an agent can identify it immediately.

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

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

It gives clear timing guidance: 'Call at session start,' plus conditional follow-up instructions for updateAvailable and dbSchemaStatus. It does not explicitly state when not to call it or name alternatives, but the usage context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: it explains the aggregation logic, the quote treatment of notes, and—most usefully—that the response carries a 'render' field with tiered guidance the agent must consult before composing a reply. It does not discuss pagination or size limits, but the pre-call guidance is strong.

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

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

Three compact sentences, front-loaded with what the tool returns before moving to use cases and the render-field instruction. No filler or repetition of the title beyond the necessary subject.

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 return-value burden, and it does so reasonably: grouping key, quote treatment, format variant, and the render field are all mentioned. Slightly more on response structure or empty-week behavior would make it fully sufficient.

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% and enums are documented, so the baseline is 3. The description restates the 'linkedin' format option but adds no semantics (e.g., how scope interacts with tag grouping, or what the LinkedIn draft contains) beyond what the schema already spells out.

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 ('completed-task retrospective for a given week') and even describes the aggregation shape (grouped by first tag, notes as quotes, optional LinkedIn draft). It does not, however, name or contrast with the nearest siblings such as get_task_summary or get_project_history, so sibling differentiation is left implicit.

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

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

Gives clear usage context ('weekly reviews, standup prep, and public updates') which is enough to know when to reach for it, but there are no exclusions or explicit routing rules telling the agent when to prefer get_task_summary or get_project_history instead.

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

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

Annotations already declare non-read-only, open-world, idempotent, and non-destructive behavior. The description adds useful domain behavior: existing subscriptions are skipped and a subset of feeds is pinned by default for the morning briefing, an important side effect; it still omits scale, undo behavior, and return details.

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

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

Three short sentences, front-loaded with the action and scope. The category list is compact, and each sentence adds distinct value: scope, existing-subscription handling, and default pinning.

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 zero-parameter bulk action with annotations covering safety and idempotence and no output schema, the description is mostly complete. It covers scope, skip-existing behavior, and default pinning, though scale and undo/briefing impact could be clearer.

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 has zero parameters, so the schema is complete and the baseline is 4. The description correctly implies there are no input choices rather than inventing parameter details.

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 ('Import') and resource ('curated starter feed list'), plus the content categories it covers. This distinguishes it from single-feed siblings like subscribe_feed, though it does not explicitly name the alternative.

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 explicit when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. Usage is implied as onboarding or bulk setup versus individual subscriptions via subscribe_feed.

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

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

The annotations already declare this is a non-destructive, non-open-world mutation, so the safety profile is covered. The description adds one genuinely useful behavioral fact — duplicate links are silently ignored, so the agent knows repeats will not error — but it does not say what happens if the task or entity id is invalid, nor what the call returns. There's also a mild tension with idempotentHint=false, since dedupe-on-repeat reads as idempotent-like behavior, though this refers to the link record rather than the whole operation.

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

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

Three short sentences with the core action and supported entity types front-loaded; every sentence carries information (scope, multiplicity, duplicate behavior) with no filler.

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

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

For a simple three-parameter mutation with full annotation coverage and no output schema, the description covers purpose, scope, and duplicate handling adequately. The only real gap is failure behavior for invalid ids, which an agent would reasonably want before calling.

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% and all three parameters are required, so the schema already documents task_id, entity_id, and the entity_type enum. The description restates the entity types but adds no format, ordering, or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (Link) and resource (a task) plus the full set of supported link targets (customer, contact, transaction, contract, memory, interaction). That enumeration makes it easy to separate from siblings such as unlink_task, list_entity_tasks, and get_entity_card without opening any schema.

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

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

Usage is implied by the alternate-sounding siblings (unlink_task, list_entity_tasks), but the description never states when to prefer this tool, what prerequisites exist (e.g., whether the task and target entity must already exist), or any when-not condition. It only clarifies that a task may hold multiple links, which is useful but not full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact — that balances are computed and returned — but says nothing about default exclusion of archived accounts or how tag filters combine, which are the only non-obvious behaviors here.

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; every word earns its place. It is arguably too spare given four filter parameters, but there is no bloat or redundancy.

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

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

For a four-optional-parameter read-only list tool there is no output schema, so the description's note that balances are returned is valuable and the annotations cover safety. Still, an agent gets no statement about default result scope (archived excluded) or relationship to the add/remove/transfer siblings, leaving gaps for a tool in a crowded financial namespace.

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

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

Schema description coverage is 100%, so every parameter including tag vs tags, tag_match semantics and include_archived is already documented in the structured data. The description adds no additional meaning about filtering behavior, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List all capital accounts') and adds scope detail ('with their current balances'), which distinguishes it from mutation siblings like add_account, remove_account and transfer_between_accounts. It does not, however, explicitly contrast with adjacent listing tools such as list_transactions or mention the tag/archived filtering the schema supports.

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 reach for this tool versus siblings — no mention of how to narrow results by tag, whether archived accounts are excluded, or that add_account/remove_account manage the same resource. Usage is only inferable from the name and the schema properties.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds the meaningful behavioral trait that results are ordered newest first, but says nothing about pagination behavior or result caps beyond what the schema shows.

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

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

Two tight sentences with the core action and ordering front-loaded, then the return fields. No filler, though the return-field sentence is somewhat enumerative and could be trimmed if an output schema existed.

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 two-optional-parameter list tool with full annotation coverage and no output schema, the description covers what the tool does, the ordering, and the shape of each returned item. Only a note on pagination behavior is missing, and the schema largely supplies that.

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

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

Schema coverage is 100% and both parameters (limit, offset) carry descriptions, so baseline is 3. The 'newest first' ordering does add useful framing for how offset paging behaves, but the description adds no detail about limit/offset syntax or defaults.

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

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

States a specific verb ('List') and resource ('saved feed item bookmarks') plus the ordering ('newest first'), which is enough to distinguish it from bookmark_item and remove_bookmark. It does not explicitly differentiate from the broader get_feed_items sibling, so it falls short of a 5.

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

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

The description implies usage (retrieving previously saved bookmarks) but never says when to prefer this over get_feed_items for all items, or points to bookmark_item/remove_bookmark. An agent can infer the intended use from the name and text, but there are no explicit alternatives or exclusions.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. Beyond that the description adds only the domain word 'financial', and it omits any note that archived categories are excluded by default (that fact lives only 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?

A single short sentence with the core purpose front-loaded and zero filler. It is efficient, though it is arguably undersized given the five filtering parameters available.

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, non-destructive read tool with full schema coverage, rich annotations, and no output schema, the description plus structured fields give an agent everything needed to call it. Only soft gaps remain, such as the default exclusion of archived categories being documented solely in the schema.

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

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

Schema description coverage is 100%, so all five parameters (tag, tags, type, tag_match, include_archived) are already documented in detail, including enum semantics and the all/any tag combination rule. The description mentions only the type filter, adding nothing beyond the schema; baseline 3 applies.

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

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

The description names a specific verb and resource ('List all financial categories'), which clearly distinguishes it from the mutation siblings add_category and remove_category. It stops short of naming those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

The only usage cue is the phrase 'optionally filtered by type', which hints at filtering but never says when to call this versus add_category, list_tags, or other listing tools. There are no exclusions, prerequisites, or alternative routing hints.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds genuinely non-obvious behavior beyond that: results are paginated, responses carry summary info, and a 'render' field with tiered rendering guidance must be consulted before replying. It stops short of explaining pagination limits or how to detect the end of results, which is what would push this higher.

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

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

Three short sentences, front-loaded with the operation and then the return shape, with no filler wording. The final sentence about the render field is the one piece of information an agent could not obtain from schema or annotations, so it earns its place.

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

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

For a nine-parameter read tool with no output schema, the description covers the essentials: what is returned (paginated, summary info) and the one non-standard response element (the render field) that requires action. Combined with 100% schema coverage and complete read-only annotations, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, with all nine parameters documented including enum values, defaults, and the tag/tags/tag_match interaction, so the baseline of 3 applies. The description only says 'optional filters' generically and adds no filter-selection strategy or combination advice beyond what the schema already states.

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

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

States a specific verb and resource ('List customers') plus the scope ('with optional filters'), so the agent knows exactly what entity is being read. It does not, however, distinguish itself from the sibling search_customers, leaving the agent to guess which list/query tool applies.

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 or when-not-to-use guidance and no reference to alternatives such as search_customers or get_customer for single-record retrieval. The line about checking the render field is a response-handling instruction, not usage routing, so an agent gets no help choosing between this and its closest sibling.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's job is to add context, and it does: soft-deleted-only scope, 7-day default window, demo fixtures hidden by default, per-item auto-purge dates, and an instruction to consult the render field before replying. It stops short of describing pagination behavior or what happens at the limit boundary, which is the main remaining gap.

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

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

Purpose is front-loaded in the first sentence, followed by return contents, parameter overrides, and the id/label rule in a logical order. It runs four dense sentences, and the final note about the render field is useful but slightly meta, keeping it below a perfect score.

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 carries the burden of explaining return values and does: item type, human-readable label, deletion time, auto-purge date, plus the entity_id and render field. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so the baseline is 3; the description earns a point by framing intent ('pass days to widen the window', 'include_demo to show demo data') rather than merely restating the schema's type and default. It does not add syntax or format detail the schema lacks, which is why it is not a 5.

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 verb and resource with scope: 'List recently soft-deleted items (the recoverable trash) for the current company.' The parenthetical and the stated follow-up goal ('so the user can pick one to restore or permanently delete') separate it cleanly from list_demos, restore_item, purge_item, and the other list_* 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?

Explicitly states the use case (choosing an item to restore or purge), names the follow-up tools restore_item and purge_item and the entity_id that links to them, and documents the defaults and when to override them (days to widen the window, entity_type to filter, include_demo to surface demo data). It also adds a usage rule for the agent's reply: present by label, never by id.

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

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

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower, and the description still adds real value: it discloses the dual return shape (summary list vs. full script) and that the full script has shared presentation rules prepended so the agent can run it directly. It does not cover what happens if an unknown demo name is supplied, nor how large the script payload is.

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 what the tool returns, then the two modes, then the usage trigger. Every sentence contributes a distinct fact and there is no filler or repetition.

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-optional-parameter, read-only tool with full annotation coverage and no output schema, the description covers both invocation modes and what each returns, which is close to sufficient. The remaining gap is edge behavior for an unrecognized demo name and the shape of the summary list, which an agent would have to discover by calling.

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% and the single optional parameter already documents both the example value and the 'omit to list all' semantics, so the schema carries the load. The description only reinforces the mode split and adds that the loaded script is directly runnable, which is a marginal increment rather than new parameter-level meaning.

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

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

The description gives a specific verb and resource ('Returns available interactive demo walkthroughs bundled with Founders OS') and immediately splits the behavior into two modes, so an agent knows exactly what the tool yields. It stops short of distinguishing itself from adjacent discovery tools in the sibling list such as show_capabilities or get_usage_guide, which serve a similar exploratory purpose.

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

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

It states clear triggering conditions: 'when a user asks about demos, wants to explore features, or is onboarding.' That is concrete context for invocation. However, it never names an alternative tool or says when NOT to use it, even though show_capabilities and get_usage_guide are plausible competitors for 'explore features' requests.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds little beyond that - notably it never mentions that results default to excluding done tasks, a behavioral trait only found in the status parameter's schema text.

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

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

One front-loaded sentence with no filler. It is appropriately sized for a simple read tool, though it spends its limited words on redundant enum examples rather than differentiating sibling tools.

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 low-complexity read-only list tool with full schema coverage and clear annotations, the description is adequate but thin: it omits the default exclusion of done tasks and does not position itself against list_tasks, leaving the agent to infer selection.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including enums and the default status filtering. The description's parenthetical entity examples merely restate part of the entity_type enum and add no format or semantics 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?

The description gives a specific verb and resource ('Get all tasks') plus the scoping condition ('linked to a specific entity') with examples of entity types. It is clear what the tool returns, though it does not distinguish itself from the sibling list_tasks, which the agent must guess at.

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: use it when you know an entity and want its tasks. There is no explicit guidance on when to prefer this over list_tasks or list_interactions, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond them by describing what is returned: feed metadata from the shared catalog plus per-user tags and pinned status — important since no output schema exists. It omits ordering and pagination behavior, which keeps it from a 5.

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

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

Two sentences, zero filler: the first states the operation and filters, the second states the return composition. Scope is front-loaded and nothing is repeated.

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 two-parameter, zero-required read tool with full schema coverage and annotations, the description covers purpose, filtering, and return shape. Only ordering/pagination of the feed list is left undefined, a minor gap given 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 description coverage is 100%, including an example for 'tag' and a stated default for 'pinned_only', so the schema does the heavy lifting. The description only restates that filtering is by tag or pinned status, adding no syntax or edge-case meaning 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?

The description gives a specific verb and resource ('List all subscribed RSS feeds') plus the optional filter dimensions. It implicitly distinguishes itself from siblings like get_feed_items (items, not feeds) and subscribe_feed/unsubscribe_feed, though it never names them explicitly.

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

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

Usage is implied by the description ('subscribed feeds', optional tag/pinned filters), but there is no explicit when-to-use guidance, no statement of when-not-to-use, and no pointer to alternatives such as get_feed_items or preview_tags. An agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only the customer-scoping and filter behavior; it says nothing about pagination behavior (default 50, capped at 100), result ordering, or the presence of deprecated since/until fields that an agent might otherwise reach for.

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, leading with the core verb and resource before the optional filters. It is efficient, though its brevity is partly under-specification rather than deliberate compression.

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

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

Annotations cover the read-only, idempotent safety profile and the schema fully documents all seven parameters, so the description's short scope statement is close to sufficient for a filtered list tool. The missing pieces are pagination expectations (limit default 50, max 100) and, absent an output schema, any hint of the returned record shape.

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%, including ISO 8601 formats, the enum of interaction types, and the deprecation notes on since/until, so the schema carries the parameter burden. The description merely echoes the date-range and type filters and omits limit entirely, adding no syntax or semantic detail 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 ("Get interaction history") scoped to a customer, so an agent knows exactly what data comes back. It does not, however, distinguish itself from nearby siblings such as log_interaction, remove_interaction, or list_demos, leaving that separation to inference.

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

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

The description never says when to use this tool versus log_interaction or remove_interaction, nor does it state prerequisites such as the customer needing to exist. Usage is only implied by the phrase "for a customer" and the filter mention, with no exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds a genuinely useful authorization detail (no owner role required to view), but says nothing about result volume, pagination, or ordering for large rosters.

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 what is returned, followed by the permission clarification. Nothing is wasted and nothing is buried.

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

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

For a no-parameter, no-output-schema, read-only listing tool, the definition covers what it returns and who may call it. It would be complete with a note on roster size or ordering, but the essentials are present.

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

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

There are zero parameters, so the baseline is 4; the description correctly conveys that the call is unscoped and takes no filters, meaning the full company roster is returned.

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 ('List all team members in this company') and names the attributes surfaced (owner status, financial access level), which distinguishes it from siblings like add_member, set_member_owner, and remove_member.

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

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

It states a permission-related usage fact — any member can call it without being an owner — which implies this is the read-side roster tool versus the mutation siblings. However, it never explicitly says when to prefer it over, say, get_financial_access or get_entity_card, so routing guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile needs no restating. The description adds nothing beyond that: it doesn't say what the history contains (running vs completed vs failed runs), the default ordering, or whether results are paginated.

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; the purpose is front-loaded and the filtering note follows. Nothing is redundant, though the phrasing is terse enough that it borders on under-specification.

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 no-required-parameter read-only list tool with fully documented params and no output schema, the core is covered. What an agent still lacks is any sense of result ordering, pagination beyond 'limit', or what fields a run record exposes.

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% and all three parameters carry their own descriptions, so the schema does the heavy lifting. The description merely mirrors the two filter parameters and omits the limit parameter, adding no syntax or format detail 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?

The description gives a specific verb and resource: 'List playbook execution history.' This clearly separates it from get_playbook_run (singular) and run_playbook, 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?

'Optionally filter by playbook or customer' implies when the filters apply, but there is no guidance on when to use this list tool versus get_playbook_run for a single run, or list_playbooks for definitions. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by naming the returned fields (name, slug, description, step count) and disclosing the default filtering of archived playbooks, which an agent would otherwise only discover after calling.

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

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

Three short sentences, front-loaded with scope, then return shape, then default filtering behavior. No filler and nothing an agent must read past to find the essentials.

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 one optional parameter, no output schema, and full annotation coverage, the description supplies what is needed: scope, return fields, and the archived default. Minor gaps such as ordering or result limits are unlikely to mislead for a simple enumerating read.

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% and the single include_archived parameter is fully documented there, so the baseline is 3. The description's 'Archived playbooks are hidden by default' largely restates what the schema already says, adding only mild emphasis rather than new meaning.

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

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

The description opens with a specific verb+resource ('List all defined playbooks for this company') and is clearly distinguishable from get_playbook, create_playbook, and list_playbook_runs. It stops short of naming a sibling or explicitly contrasting with detail-oriented retrieval, which keeps 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?

Usage is only implied by the list semantics; there is no explicit 'use this when you need an overview, use get_playbook for a single playbook's full steps' routing. The one guidance offered is the archived-visibility default, which is genuinely useful but narrow.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: results are enriched with per-project task counts computed via tag lookup, and the call has a side-effect-free auditing purpose (surfacing #-tags with no project record). Missing only ordering or result-size expectations.

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 with the resource, the default scope, and the return payload presented in that order. No filler, no restatement of the tool name, and the least obvious behavior (the tag-flagging audit) is placed last where it does not crowd the core purpose.

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 return-value burden and does so by naming task counts and orphan-tag flags. For a two-optional-parameter read tool this is nearly complete; the only unaddressed points are result ordering and how status and include_all combine.

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

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

Schema description coverage is 100%, so both status and include_all are already documented, including the omit-for-active default. The description restates that default but adds nothing about the interaction between status and include_all (e.g., which wins if both are supplied), so it does not exceed the schema.

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

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

The description states a specific verb and resource ('List registered projects') and immediately pins down scope ('Defaults to active projects only'), which separates it from the singular get_project. It also names what comes back (task counts per project, orphaned #-tags), so an agent knows this is a batch-listing tool rather than a detail fetch.

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 default-to-active behavior is stated, and the schema's include_all parameter makes the alternative path discoverable. However, there is no explicit when-to-use guidance — it never says to prefer get_project for a single project's details, nor when the orphan-tag audit is the reason to call this.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description still adds value beyond that by enumerating the returned fields (name, slug, color, description) — useful since no output schema exists — and by scoping results to the current company. It omits pagination/limits and the default exclusion of archived tags, which keeps it from a 5.

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

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

Three short sentences, each earning its place: purpose and scope first, return shape second, usage context third. No hedging, no redundant 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 a two-optional-parameter read-only listing tool with full annotation coverage, the description supplies what the structure cannot: the result shape and a reason to call it. The only meaningful gap is not distinguishing itself from preview_tags, which could lead an agent to pick the wrong listing 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 100%, and both parameters (scope enum, include_archived) are fully documented in the schema with their defaults and semantics. The description never mentions either parameter, so it adds no meaning beyond the structured fields — 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 a specific verb and resource ("List all registered tags") plus the scope ("for the current company"), which is more than a name restatement. It does not distinguish itself from the sibling preview_tags, so an agent must guess which listing variant it wants.

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

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

"Use this to see what tags are available before tagging tasks or customers" gives a concrete use case, which is better than nothing. However, there is no when-not guidance, no mention of scope/archived filtering choices, and no differentiation from preview_tags or the create/rename/remove siblings.

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