Trooth

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

Annotations already declare destructive=true, idempotent=true, and readOnly=false, but the description still adds real value beyond them: the effect takes hold on the next call rather than instantly, self-revocation is permitted regardless of area, cross-key revocation requires settings:write and human approval, and an owner/admin can revoke any key. The repeat-call behavior ('already revoked changes nothing') restates the idempotentHint, which is minor redundancy rather than a contradiction.

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 clauses, each carrying a distinct fact, with the core effect front-loaded before the permission and approval detail. There is no filler and nothing a caller would need to re-read.

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 destructive, zero-required-parameter tool with full schema coverage, an output schema, and annotations, the description covers effect timing, both invocation modes, authorization, the approval loop, and no-op behavior on repeat calls. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: self and key_id are alternative modes rather than free-form inputs, key_id values come from trooth_agent_keys_list, and the approval flag drives a re-invocation. Only 'workspace' is left entirely to the schema, which documents it adequately.

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 ('Revokes one agent key'), states scope ('one ... at once'), and names the observable effect ('stops working on its next call'). The resource 'agent key' plus the pointer to trooth_agent_keys_list separates it from trooth_api_key_revoke and the other key siblings without the agent needing to open 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?

It gives explicit routing conditions: use self=true to revoke the calling key, use key_id (sourced from trooth_agent_keys_list) to revoke another key. It also states the prerequisites for the second path (settings:write plus a person's approval) and the follow-up step ('call again once approved'), so the agent knows both when to pick each path and what to do when the approval gate blocks 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 readOnlyHint, idempotentHint and destructiveHint=false, so the description is not carrying the safety burden alone; it still adds real value by naming the required credentials, describing the returned fields (name, prefix, areas, expiry, last used, creator, this_key), and reassuring that no secret is ever returned. Pagination behavior via cursor/next_cursor is also disclosed. It stops short of rate limits or ordering guarantees, so not a 5.

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

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

Front-loads the authorization gate, then the resource, then the return shape, then pagination and the read-only note — a logical order with no filler. The opening auth sentence is dense enough that a reader must parse it carefully, keeping it just below top marks.

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

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

For a read-only list tool with an output schema, an auth gate, full param docs and annotations, the description covers everything an agent needs: who may call it, what comes back, and how to page. Nothing material 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 limit, cursor and workspace are already fully documented, including the cid_ pattern and default page size. The description only restates pagination ('cursor and next_cursor page it'), adding no syntax or edge-case meaning beyond the schema, which matches the baseline 3.

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 ('Lists the workspace's agent keys') and pins the scope to the workspace, which cleanly separates it from the broader trooth_api_keys and from the mutation sibling trooth_agent_key_revoke. An agent can identify the correct tool from the first clause alone.

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

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

Gives concrete preconditions for use: an owner/admin trooth.co sign-in, or a tra_ agent key carrying audit:read as the Bearer. It does not explicitly route to alternatives (e.g. 'to revoke a key use trooth_agent_key_revoke'), but the auth and scope conditions are enough to decide when this tool applies.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description rightly focuses on semantics the annotations cannot convey: that each row is the company's own self-declaration, labeled as such, with a separate Trooth-observed policy-clause flag. The explicit warning that 'not observed' means Trooth has not read a clause — never that the company does not train on customer data — is exactly the interpretive guard an agent needs. It stops short of describing result size, no-match behavior, or auth scope.

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 verb and resource, then the provenance caveat, then the read-only tag; nothing is padded. The middle sentence is dense with nested parentheticals and commas, which slightly slows parsing, but every clause carries substantive 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?

With one parameter, full schema coverage, an output schema, and complete annotations, the description covers the remaining gap well: data provenance and the risk of misreading a missing observation as a negative fact. Only edge behavior — no match found, result volume — is left unaddressed, which is minor given the output schema.

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

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

Schema coverage is 100% with a documented example, so the baseline is 3. The description does add one useful nuance beyond the schema — that matching is exact against either a domain or a Trooth slug — but it restates rather than expands the parameter's meaning, and offers no format hints for slug shape.

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

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

Opens with a specific verb+resource: 'Read what one company ... has declared about AI and customer data', and enumerates the substance (model training, AI in product, approaches). It is clearly distinct from siblings like trooth_list_companies or trooth_public_trust_profile by naming the exact resource and single-company scope, though it never names an alternative outright.

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

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

Usage is implied rather than stated: you use it to inspect one company's AI/data-use declarations, and 'matched exactly' signals no fuzzy lookup. But there is no explicit when-to-use-vs-siblings guidance (e.g., versus search_companies, list_companies, or public_trust_profile), and no stated behavior when the exact match fails.

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 non-read-only, idempotent, open-world behavior, and the description adds real context beyond them: the credential model (trooth.co sign-in or Bearer tra_ agent key), that workspace scope is derived and never an argument, that agent-key calls require human approval (approval_required), and that webhooks must satisfy a verification challenge. That is substantive operational disclosure; the only gap is the exact response/error shape.

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

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

Compact overall, but the opening is a sentence fragment ('With your trooth.co sign-in, or the workspace's agent key with the settings area (Bearer tra_...).') that reads as a clipped clause rather than a clear statement. Information density is good, but the broken syntax costs readability.

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

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

An output schema exists, so return values need not be explained, and the description covers auth, workspace scoping, approval, webhook verification and the duplicate/self-answering case. What remains thin is how a duplicate add is reported to the caller and whether 'events' defaults to all events.

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 every property is self-documented, so the schema carries the parameter burden. The description only restates kind and target semantics and clarifies that workspace is not a parameter, adding little beyond structured data — 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 ('Adds one alert destination') and enumerates the accepted kinds and target form, with an analogy to the Settings > Notifications UI. It does not explicitly name the sibling it complements (trooth_alert_destination_remove), 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?

Gives useful context about the approval path with an agent key and the fact that a webhook must first answer a challenge, which tells the agent what to expect. However it never says when to prefer this over adjacent tools such as trooth_webhook_add or trooth_notifications_update, so the 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?

Goes well beyond the annotations: it discloses that the workspace is derived from the sign-in or agent key and never from an argument, that an agent-key call requires human approval (approval_required), that a foreign id yields not_found and "changes nothing," and that Trooth simply stops sending to the destination. Those are exactly the mutation consequences the destructiveHint flag cannot convey.

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

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

The authentication and workspace-derivation sentences are placed ahead of what the tool actually does, delaying the core action. Phrasing like "as Remove does" is cryptic and does not earn its place; the content is valuable but the ordering is not front-loaded.

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

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

For a one-parameter destructive mutation with an output schema present, the description covers auth model, approval flow, error behavior, and effect on delivery, which is nearly everything an agent needs. Only the reversibility of a removal 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 coverage is 100% for the single id parameter, so the baseline would be 3; the description earns higher by telling the agent where the id comes from (trooth_notifications_get) and warning that it is never derived from an argument. It does not add format detail, but the schema already constrains length.

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: "Removes one alert destination" by id, and names the sibling that supplies the id (trooth_notifications_get). An agent can distinguish this from trooth_alert_destination_add or trooth_webhook_remove 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?

Gives clear preconditions and the correct id source ("by the id trooth_notifications_get gives") and explains the agent-key approval path, which is what determines whether a call succeeds. It stops short of explicit when-not-to-use guidance or naming a recovery alternative after a not_found.

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

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

Beyond the annotations (non-read-only, non-idempotent), the description discloses behavior an agent could not infer: the secret appears exactly once in structuredContent key.secret and never again in text, agent-key creation blocks on a person's approval, and the workspace is derived from credentials rather than arguments. These are exactly the traits that change how an agent should call and post-process this tool.

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

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

The content is dense and largely value-adding, but the opening sentence is a grammatical fragment ("With your trooth.co sign-in, or the workspace's agent key with the developer area (Bearer tra_...)") that leads with auth rather than purpose. Front-loading the auth clause before the verb+resource costs scanability.

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 an output schema exists, the description wisely limits return-value detail to the one non-obvious fact (the secret's single appearance in structuredContent). Auth source, workspace scoping, approval flow, and key-type selection are all covered; only edge cases such as naming collisions or approval timeouts go 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 coverage is already 100%, so the baseline is 3; the description adds genuine meaning on top by stating that omitting public_key_thumbprint produces an ingest key and that no workspace argument is needed because scope comes from credentials. It does not elaborate on the permissions object beyond what the schema 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?

The description gives a specific verb and resource: "Makes one secret key for the Trooth API," and anchors it to the dashboard equivalent ("as Create secret key on trooth.co/dashboard/api-keys does"). It also distinguishes key variants (standard vs. restricted vs. ingest). It stops short of explicitly naming the sibling listing/revocation tools, so differentiation from trooth_api_keys and trooth_api_key_revoke is mostly inferred from the name.

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 implied rather than stated: it explains that an agent key's request waits for human approval and that omitting public_key_thumbprint yields an ingest key, which implicitly guides parameter choice. There is no explicit "use this instead of X" routing to trooth_api_keys or trooth_api_key_revoke, and no stated prerequisites or failure conditions beyond the approval wait.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces them with real consequence detail: 'every call with it is refused from then on, and it cannot be undone.' The extra note that an agent key's request waits for human approval is valuable disclosure of an asynchronous gate, but the description never says what the caller sees while approval is pending or after a denial, which matters for a destructive action.

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 sentences are dense but the ordering is poor: the text opens with a sentence fragment about sign-in credentials before ever stating what the tool does, pushing the actual action into the middle. The content is mostly earned, but a purpose-first arrangement would serve an agent scanning tool definitions far better.

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 annotations covering safety profile and an output schema covering returns, the description carries only the pieces those cannot: auth path, workspace scoping, irreversibility, and idempotency. The remaining gap is the approval flow's observable outcome for the agent-key case and no explicit disambiguation from trooth_agent_key_revoke.

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 there is a single well-documented parameter, so the baseline is 3. The description earns above baseline by stating 'Takes key_id from trooth_api_keys,' telling the agent where to obtain the value rather than leaving it to guesswork.

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 ('Revokes one secret key for the Trooth API') and anchors it to a concrete UI equivalent ('as Revoke on trooth.co/dashboard/api-keys does'). It does not explicitly contrast itself with the close sibling trooth_agent_key_revoke, so an agent must infer that this handles secret API keys rather than agent keys.

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 operating context: the credential to authenticate with, that the workspace derives from the credential and not from an argument, and that repeat calls are no-ops. It stops short of naming alternatives such as trooth_agent_key_revoke or trooth_api_keys for other key operations, so routing between siblings still requires inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description goes beyond that with the authentication model (sign-in or developer-area agent key), the fact that workspace scope comes from the credential and never from a parameter, and a security guarantee that secrets are never returned. It also discloses pagination behavior (cursor-based) and the full field surface, which the annotations say nothing about.

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 text is dense and nearly every clause carries information: auth mode, scope derivation, contents, secret-free guarantee, pagination, read-only. The weakness is ordering — it opens with an authentication fragment before stating the purpose, and several sentences are telegraphic fragments, so the primary action is not front-loaded.

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

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

For a two-parameter, read-only list tool with a full output schema and complete annotation coverage, the description supplies everything an agent needs to call it correctly: auth, implicit workspace scoping, page size behavior, and the security constraint. Only minor gaps remain, such as error conditions for an invalid or revoked credential.

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, cursor) are already documented with bounds and defaults in the schema, so the description adds little beyond noting "Pages with cursor." That line confirms pagination is cursor-based but adds no syntax or semantics the schema lacks, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Lists the workspace's API keys") and immediately bounds the scope by naming what it is not — "not agent keys" — which separates it from the sibling trooth_agent_keys_list. It also enumerates the returned fields (id, name, prefix, timestamps, status flags), so the agent knows exactly what this tool surfaces 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?

The description gives clear selection context: this is the dashboard API-keys listing, not the agent-keys listing, and it works with either a trooth.co sign-in or a developer-area agent key (Bearer tra_...). The workspace scope is explicitly derived from the credential rather than an argument, which prevents a common misuse. It does not, however, point to trooth_api_key_create or trooth_api_key_revoke as the mutation counterparts, so the routing guidance is implicit rather than exhaustive.

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

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

Annotations already declare non-read-only, idempotent, open-world and non-destructive, and the description adds real context beyond them: the store listing is fetched and read remotely, the submission records a claim rather than an instant verification, and a human must confirm publication in the Apps tab. That pending-human-approval flow is the key behavioral fact and is not derivable from the annotations. It does not describe failure behavior for an unreachable or already-claimed listing, so it is not exhaustive.

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

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

Three short sentences, front-loaded with the action and credential requirement, then the input format, then the approval consequence. Every sentence carries information, though "as the Apps tab does" and the slightly ambiguous "It states you act for someone authorized..." could be tightened.

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 tool with an output schema and full annotation coverage, the description supplies the remaining essentials: auth scope, input source (store listing), the claim-recording nature, and the human confirmation step. Return-value details are correctly left to the output schema, so nothing an agent needs before calling 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%, with both url and workspace fully documented in the schema, so the schema carries parameter meaning. The description reinforces that url must be an App Store or Google Play link but never mentions the workspace parameter or its multi-org selection semantics, adding little beyond the structured fields. Baseline 3 is appropriate here.

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: "Adds one app by its App Store or Google Play link," and names the exact input format. This clearly separates it from trooth_apps (listing) and trooth_app_remove (removal) without the agent 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?

Gives the credential precondition explicitly ("your trooth.co sign-in (or an agent key with profile:write)") and frames the operation as the API equivalent of the Apps tab, which tells the agent when this is the right call. It does not name the sibling to use instead for removal or listing, leaving that inference to the obvious naming, so it falls short of full alternative 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?

Beyond the annotations, it discloses the observable effect ("the app leaves the public page") and the non-trivial post-removal semantics that re-adding creates a fresh claim rather than restoring the old one. It does not contradict destructiveHint=false or idempotentHint=true; repeated removal is consistent with the stated 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 compact clauses ordered auth, action, consequence, with no filler. 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 destructive-adjacent removal with an output schema available, it covers credentials, targeting, effect, and re-add behavior. The only minor gap is not naming the sibling add tool explicitly as the way to restore the claim.

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 required parameters are already documented, including the enum and the "as trooth_apps gives it" guidance. The description's "by store and appId" only restates the schema, 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?

"Removes one app claim by store and appId" gives a specific verb and resource plus the scoping keys, and "as trooth_apps lists it" anchors it to the sibling listing tool. An agent can distinguish this from trooth_app_add 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?

It states the prerequisite credential (trooth.co sign-in or an agent key with profile:write), which is the main gating condition. It also implies the add-then-remove lifecycle via "Adding it again starts a new claim," but never explicitly names trooth_app_add as the inverse operation.

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 'Read only' merely restates them. The description does add real value beyond the annotations by disclosing the authorization requirement (sign-in or profile:read agent key) and by describing the shape of each returned claim, which no annotation conveys.

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

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

Three short sentences: auth requirement first, then the substantive description of returned claims, then a safety flag. Nothing is redundant and the most decision-relevant information is front-loaded.

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

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

With an output schema present and annotations covering the safety profile, the description needs only purpose, auth, and result shape — all supplied. The only modest gap is scope/volume (whether all apps are returned or results are bounded), which the agent would have to infer from the 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% and the single optional workspace parameter is documented in the schema down to its cid_ pattern and when to omit it. The description adds no further meaning about the parameter — its mention of sign-in scope overlaps what the schema already says — 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 ('Lists the Apps tab's app claims') and enumerates exactly what each claim contains: store, appId, name, and publisher confirmation. This cleanly separates it from the mutation siblings trooth_app_add and trooth_app_remove without the agent 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?

Gives the operative context for calling it — you need a trooth.co sign-in or an agent key carrying profile:read — which tells the agent when the call will succeed. It stops short of naming alternatives or exclusions (e.g., 'to add an app use trooth_app_add'), but for a straightforward listing tool the usage condition is clear.

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, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: the answers come from a fixed, curated knowledge base, no outside request is made, and misses produce an out_of_scope result instead of a generic error.

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 verb and scope, with the sibling redirect last where it is most useful. The parenthetical topic list is dense but earns its place by scoping the tool; nothing is filler.

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

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

An output schema exists, so return values need not be explained, and the description still flags the out_of_scope outcome. For a one-parameter lookup tool, an agent has everything needed to call it correctly and to route elsewhere when the question is about a company.

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 already documented with its maxLength, so the schema does the heavy lifting. The description still adds meaning by defining what counts as a valid question (Trooth itself: network, record contents, pricing, methodology) and repeating the 500-character ceiling.

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 (answer a question) and resource (Trooth itself), then enumerates the in-scope subject matter: the Trooth Network, what a company record carries, pricing, and how witnessing works. It also names the sibling trooth_public_trust_profile as the tool for company records, so the boundary is unambiguous.

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

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

It states clearly when to use this tool (questions about Trooth the product, not about a company) and explicitly redirects to trooth_public_trust_profile for a company's record. It also describes the failure path: an uncovered question returns out_of_scope, which tells the agent how to interpret the result.

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 the authorization model, the preview-versus-commit split, and the external side effect that "Trooth emails them a link only they hold." It also conveys a privacy property (the answer belongs to the recipient alone) that no annotation or schema field expresses. Nothing conflicts with readOnlyHint=false, openWorldHint=true, or destructiveHint=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?

Three dense sentences with no filler, and the preview/commit distinction is stated crisply. The only structural quibble is that it leads with the auth prerequisite rather than the action, delaying what the tool does until the second sentence.

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

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

For a 10-parameter mutation with an output schema and annotations already present, the description covers the gaps that matter: permission requirements, preview versus send, the external email side effect, and recipient privacy. An agent has enough to decide whether to call it and how to avoid an accidental send.

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 adds real meaning by explaining what confirm actually triggers downstream (an emailed single-holder link), not just its type. Other parameters such as scope, workspace, and idempotency_key are left to the schema, so it does not fully compensate where it could.

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: "Asks one named person to confirm one statement about the company." The clause "as the Attestations tab does" separates this send-an-ask action from the read-only listing sibling trooth_attestations, so an agent can tell the two apart 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 clear preconditions (a sign-in role that may publish, or an agent key with profile:publish) and explains the dry-run path: "Without confirm true it is a preview that writes and sends nothing." It never explicitly says when to prefer a sibling, such as reading existing attestations via trooth_attestations before asking, so the alternative-routing guidance is incomplete.

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 structurally and "Read only" merely restates it. The description earns credit for adding auth-scope context not present in annotations: a publishing role via sign-in, or an agent key with profile:read. It says nothing about result volume, ordering, or pagination 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 with no filler, and the final "Read only" is arguably redundant against readOnlyHint. The ordering is slightly off — the auth prerequisite leads while the actual purpose arrives second — so the key identifying clause is not fully front-loaded.

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

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

For a zero-required-parameter read tool with an output schema and full safety annotations, most of the burden is already carried structurally, and the description covers auth scope and record shape. Gaps around result boundaries (all requests? paged? filtered by status?) are modest but real for a list operation.

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

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

Schema description coverage is 100% on the single optional workspace parameter, and the schema already explains the cid_ format, the multi-workspace case, and when to omit it. The description adds no parameter 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 ("Lists the Attestations tab's requests") and even enumerates record contents: the statement, who was asked, and their answer. That is far more concrete than a restated title. It stops short of naming the nearest sibling (trooth_attestation_request) as the contrasting single-request operation, so an agent must infer the distinction.

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 supplies a real gating condition for use — sign-in with a publishing role, or an agent key carrying profile:read — which tells an agent whether it is even eligible to call this. It gives no explicit when-to-use vs. alternatives guidance and does not mention the singular trooth_attestation_request sibling, so the choice between them 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?

The annotations already declare readOnly, idempotent and non-destructive, so the description is not carrying the safety burden. It nonetheless adds real value beyond them by specifying the authorization paths (owner/admin sign-in or a tra_ agent key with audit:read sent as the Bearer) and the newest-first ordering, which the annotations do not convey.

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

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

Three compact sentences lead with authorization, then ordering and return shape, then filtering and paging. Dense without filler, though the parenthetical '(a tra_ key sent as the Bearer)' and the trailing 'Read only.' partly repeat what the schema and annotations already establish.

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

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

With an output schema and full annotations present, the description only needs to cover auth, ordering and scope, and it does. It omits retention/coverage scope of the log and any pointer to the export sibling, which are the remaining gaps for a five-parameter read tool.

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

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

Schema coverage is 100%, so every parameter is already documented, including the cursor/next_cursor relationship and the trooth_agent_keys_list source for key_prefix. The description restates the narrowing filters without adding format or constraint detail beyond the schema, which lands at the expected 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?

The description names a specific verb and resource: it 'reads the workspace audit log on trooth.co newest first' and enumerates the returned fields (actor, action, object, time, detail). That is enough to distinguish it from most siblings, but it never contrasts itself with trooth_audit_export, the closest read-adjacent alternative, 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?

It supplies a clear motivating context — 'so an agent can read back what it did' — and indicates that actor/key_prefix narrow while cursor pages. It stops short of stating when to prefer this over trooth_audit_export or trooth_events_list, so the usage context is clear but without 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 the operation read-only, idempotent and non-destructive. Beyond them, the description adds what really matters: how the workspace is determined (from the credential, never an argument), the audit:read requirement and the insufficient_scope failure mode, the oldest-first ordering, and page-at-a-time retrieval. That is exactly the behavioral context an agent needs before 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?

It is dense but front-loaded with the access requirements before the return shape, and every clause carries information. The long semicolon-chained opening sentence makes it slightly harder to scan than it needs to be, but there is little wasted wording.

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 five-parameter read tool whose schema, annotations and output schema already cover field details and safety, the description supplies auth, ordering, paging, format and error behavior. Only minor gaps remain, such as any rate limit or large-export handling, which are unlikely to block a correct call.

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 3 would be the baseline. The description goes further by describing how the parameters work together: since and until (RFC 3339) narrow the window, and cursor with next_cursor advances the page, kept alongside the other arguments. That cross-parameter relationship is meaning beyond what the flat schema 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: exports the workspace audit log as csv or jsonl, with the same rows and columns the dashboard downloads. It does not name or contrast itself with the closest sibling, trooth_audit_events, so an agent must infer the difference instead of being routed.

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 the prerequisites and access paths clearly (a trooth.co sign-in or an agent key with audit:read sent as a Bearer token) and notes that a key without that scope gets insufficient_scope. However, it never says when to choose this tool over trooth_audit_events or describes a case in which it should not be used.

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, and closed-world, so the safety profile is covered; the description adds genuinely new context beyond them: the required credential type (owner/admin sign-in or an agent key with profile:read issued by one), newest-first ordering, and cursor-based paging. It stops short of describing rate limits or page-size behavior at the boundary, keeping it from a 5.

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

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

Short overall and mostly front-loaded, but the opening sentence is a dense run-on that puts the authentication clause ahead of the core purpose, delaying what the tool actually does. The trailing 'Read only.' is redundant with the readOnlyHint annotation, though harmless.

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

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

An output schema exists, so enumerating return fields is unnecessary, yet the description still covers auth prerequisites, ordering, and pagination — the items an agent actually needs to call it correctly. Only the absence of guidance on multi-workspace ambiguity beyond the schema's own 'workspace' note and any rate-limit context leaves a small gap.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema, which sets the baseline at 3. The description only gestures at the window via 'the profile views of the last days' and at paging via 'Pages with cursor' — it adds no format or interaction detail (e.g., that cursor must be paired with identical other arguments) beyond what the schema already says.

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 (lists the document and access requests buyers sent through the Trust Center or Network profile) and adds scope details: newest first, per-item fields (id, requester, documents, state), plus profile-view counts. An agent can distinguish this from sibling tools like trooth_buyer_request_respond or trooth_audit_events 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 implied by the framing (owner/admin reading inbound buyer activity) and by the authentication note, but the description never states when to pick this over alternatives such as trooth_audit_events, trooth_reach, or trooth_events_list, nor any exclusions. It gives context but leaves the routing decision 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?

Goes well beyond the annotations: it discloses the auth prerequisite (owner/admin sign-in or an agent key with profile:write minted by one), the concrete side effects of approve (shares the named documents and emails the requester a one-time link) and deny (sends a decline email), and the non-obvious async behavior where an agent-key approve returns status approval_required and must be re-called with identical arguments. That last detail is exactly the kind of thing no annotation conveys.

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

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

Three sentences, front-loaded with the permission requirement, then the action semantics, then the agent-key edge case. Dense but every clause carries information; the parenthetical about how to obtain the key is slightly heavy but justified for a permissioned mutation.

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 an output schema exists, the description needn't explain return values, and it still covers the things the schema cannot: authorization, side effects (document sharing plus outbound email), and the deferred-approval flow. Nothing an agent needs to invoke this 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 already 100%, so the baseline is 3, but the description adds real meaning on top: document_ids is scoped to approve only, and the retry instruction ('call again with the same arguments') clarifies that arguments are stable across the approval_required round trip. access_level is left entirely to the schema, which is a minor omission given it is optional and enum-documented.

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 pair (approves or denies) against a specific resource (one buyer document request), and anchors the resource to the sibling that produces it: 'one request trooth_buyer_activity lists.' An agent can distinguish this from trooth_buyer_activity (which reads) 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?

Usage is clear: act on a request surfaced by trooth_buyer_activity, and the description explains what each of the two actions does, which is the real selection decision here. It doesn't state explicit exclusions (e.g. that team access requests go to trooth_team_access_request_decide), so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description's 'Read only' merely echoes that. It does add real behavioral detail — oldest-first ordering, dual pagination via next_cursor and recall_cursor, and the caveat that per-fact edits appear only 'when the record carries them' — which is the strongest part of the definition.

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 required input, then the return shape. It is a single dense, run-on sentence with nested clauses about cursors and recalls, which slightly hurts readability but contains 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?

An output schema exists, so the description is not obligated to explain return values, yet it helpfully outlines the version/recall split and both cursors. Combined with full schema coverage and clear annotations, an agent has what it needs to call this correctly; only sibling disambiguation 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 all five parameters are documented structurally; the description adds only the ISO 8601 nature of 'since', which the schema already states. It does not clarify the limit default or how the two cursors interact beyond what the schema's own descriptions say, so a baseline 3 is 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 and resource ('List how one company's published record changed') and scopes it to a single company identified by domain or slug. It is distinguishable from siblings like trooth_profile_diff or trooth_updates, but it never names those siblings explicitly, so 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?

Usage is implied: supply a company (domain or slug) and optionally a since date to read its change history. There is no explicit guidance on when to choose this over trooth_profile_diff, trooth_updates or trooth_get_fact, and no prerequisites or when-not conditions are given.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses that the credential is read once to validate it, stored encrypted, never returned or logged, and that a Stripe secret key is refused. The refusal sentence ("A Stripe secret key is refused unstored") is grammatically ambiguous about whether the key is rejected or accepted, which slightly undercuts otherwise strong 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 opening sentence is a fragment ("With your trooth.co sign-in, or the workspace's agent key...") that front-loads auth before the tool's purpose, and lines like "It also passes through your AI app's own context and logs" are dense and unclear. The content is worthwhile but the ordering and grammar make it harder to scan than it should be.

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

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

With an output schema, full annotation coverage, and 100% schema description coverage, the description supplies the remaining pieces an agent needs: auth source, workspace derivation, credential validation behavior, storage handling, and credential-type preference. The only gap is the ambiguous Stripe refusal statement, which leaves a real acceptance question unresolved.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that workspace is never an argument, that the credential is read-only, and that an AWS role ARN or revocable scoped token is preferred. The idempotency behavior it describes is already documented in the schema, so not every sentence adds 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?

The description states a specific verb and resource: "Connects one provider with a read-only credential the agent holds," and clarifies scope with "one provider" and "the answer says whether the credential works." It is distinguishable from siblings like trooth_connection_disconnect or trooth_connection_resync, though the purpose is buried behind an opening sentence fragment about authentication.

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 conditions for use: you need a trooth.co sign-in or the workspace agent key with the stack area, the workspace comes from auth "never from an argument," and it recommends preferring "an AWS role ARN or a revocable scoped token." It does not explicitly name an alternative tool or state when not to use this one, which keeps it below a 5.

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

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

Goes well beyond the annotations: it discloses the auth requirement (trooth.co sign-in or Bearer tra_ stack key), that the workspace is derived from auth rather than an argument, that the stored credential survives and the connection shows as "disconnected with Reconnect", and that agent-key calls block for human approval. The approval gate is operationally critical and appears nowhere in the schema or annotations.

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

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

The opening is a sentence fragment ("With your trooth.co sign-in, or the workspace's agent key with the stack area...") that puts auth detail ahead of the core action, burying the purpose. The remaining sentences are dense but each carries useful content, so it is more awkwardly ordered than bloated.

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

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

With an output schema present, the description needn't explain return values, and it already covers auth, side effects, reversibility, idempotency, the approval gate, and parameter provenance. Nothing an agent needs in order to invoke this 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 coverage is 100% and both parameters already document that values come from trooth_connections, so the sentence "Takes provider and credential_id from trooth_connections" largely repeats structured data. No additional syntax or format guidance is added, 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?

"Switches one connection off" is a specific verb+resource, and the description states the key consequence (credential kept, connection no longer read) plus the counterpart tool trooth_connection_enable. It does not distinguish this from the sibling trooth_connection_disconnect, which an agent must choose between, 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 rather than stated: the reversible nature and "credential is kept" suggest when to prefer this over a hard disconnect, but the description never says "use disconnect instead when..." or names trooth_connection_disconnect at all. An agent gets context but no explicit routing rule.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not required to carry the safety burden. It still adds real behavioral context beyond them: the credential is permanently removed, historical 'signals it witnessed stay on the record with their dates', and the workspace scope cannot be spoofed via an argument. It does not describe the auth failure modes or what the returned payload reports.

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

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

Dense and mostly front-loaded: the outcome and its consequences arrive before the sourcing guidance. The opening auth sentence is a fragment that reads awkwardly out of order, but every sentence carries information and none are 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 a full output schema, complete parameter coverage, and rich annotations, the only remaining burdens are the destructiveness scope, idempotency, auth sourcing, and data-retention semantics — all of which are addressed. An agent has enough to call this correctly and to warn on its irreversibility.

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 property descriptions already say 'as trooth_connections gives it', so the schema does the heavy lifting. The description's pointer to trooth_connections as the origin of provider and credential_id largely duplicates that, adding no format, casing, or lookup-procedure detail.

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+resource ('Ends one connection') and immediately qualifies what ending means: the stored credential is deleted and the source is no longer read. That deletion detail implicitly separates it from the pause-style siblings trooth_connection_disable/enable, though those siblings are never named, so the agent must infer the distinction.

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 prerequisites well (workspace derived from sign-in or agent key, never an argument) and points to trooth_connections as the source of both parameters. It also notes that repeat calls are no-ops. What it never says is when to pick this over trooth_connection_disable or trooth_app_remove, which are the live alternatives for a similar decision.

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

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

Beyond the annotations it discloses authentication requirements (trooth.co sign-in or workspace agent key with the stack area, Bearer tra_...), that the workspace is derived from the credential rather than an argument, that the call mutates and immediately re-reads with the stored credential, and the exact refusal condition when a credential was deleted by a disconnect. That is substantial operational context the structured fields do not carry.

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

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

Content is front-loaded and nothing is filler, but the opening sentence is a verbless fragment ("With your trooth.co sign-in, or the workspace's agent key with the stack area...") that reads awkwardly, and the long run-on middle sentence packs authentication, mutation, re-read, and error semantics together.

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

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

With an output schema present, the description needn't explain the shape of the answer, and it correctly says the response reports whether the connection now reads. It covers auth, workspace derivation, side effects, and the credential-deleted error path; the only unstated case is what happens when the connection is already enabled, which idempotentHint partly covers.

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 schema property descriptions already say the values are "as trooth_connections gives it." The description repeats that provenance ("Takes provider and credential_id from trooth_connections") and adds the useful note that workspace is never a parameter, but adds little else about the individual parameters.

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

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

The description names a specific verb and resource ("Switches one switched-off connection on") and adds the second half of the operation ("reads it again now"). It differentiates itself from siblings by naming the failure path to trooth_connection_connect and by analogizing to Resync, so an agent can tell enable, resync, and connect apart.

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 the triggering condition clearly (the connection is currently switched off) and gives an explicit alternative for the edge case where the stored credential is gone: reconnect with trooth_connection_connect. It does not explicitly tell the agent when to prefer trooth_connection_resync over this tool, leaving that comparison partly implicit.

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

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

Beyond the annotations (non-read-only, idempotent, open-world, non-destructive) the description discloses real behavior: auth via trooth.co sign-in or a workspace agent key scoped to the stack area, and that workspace is derived from auth and never an argument. It also states the outcome semantics — what the tool returns (result, signals read, drift) and that a problem the sync doesn't fix stays open with the provider's message while the hourly sync keeps retrying.

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 dense but the ordering is off — it opens with a sentence fragment about authentication before ever saying what the tool does, which inverts the front-loading principle. Nothing is strictly wasted, but the run-on final sentence and the fragmentary opener cost 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 mutating sync trigger with an output schema, this covers everything an agent needs: auth requirements, workspace derivation, argument provenance, behavioral outcome on success and partial failure, and retry cadence. The output schema carries the return-value detail, so the description is not obliged to say more.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: both required arguments must come from trooth_connections rather than being free-form, and workspace is explicitly not a parameter. It stops short of elaborating on the provider key format or how to obtain credential_id, which the schema already covers.

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 second sentence gives a specific verb+resource — "Runs one connected source's sync now" — and anchors it to the dashboard's "Resync now" action, so there's no ambiguity about what it does. It also points at trooth_connections as the source of provider/credential_id. It loses a point only because the very first sentence is an orphaned auth fragment rather than a statement of purpose, forcing the agent to parse past 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?

It clearly frames the moment to use it: a manual, immediate re-sync of a single already-connected source, equivalent to the dashboard button, with the hourly sync as the passive alternative. It does not explicitly exclude the near-neighbors (connection_enable, connection_connect, stack_fix), so an agent has to infer that this is not for initially enabling a connection.

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, so the description does not need to restate safety. It adds genuinely new operational context: authentication via trooth.co sign-in or a workspace agent key (Bearer tra_...), the rule that workspace is derived from the credential and never from an argument, and cursor-based paging. Missing only detail on sync freshness or rate limits.

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

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

Information is front-loaded and dense, with remedial actions grouped by problem type. The opening sentence is a grammatical fragment ('With your trooth.co sign-in, or the workspace's agent key...'), which costs a little clarity but no content 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?

An output schema exists and both parameters are documented, so the description need not explain return values. It covers auth, workspace derivation, inclusion of disabled connections, paging, and remediation paths. Only the semantics of specific 'open problem' values are left implicit.

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

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

Schema coverage is 100%, so limit and cursor are already fully documented with bounds and defaults. The description only adds 'Pages with cursor', which is marginal beyond what the schema states. Baseline 3 applies 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?

Specific verb and resource (lists sources connected at trooth.co/dashboard/connect) plus the exact payload it returns: last sync, result, next run, and any open problem. It also states that switched-off connections are included, which distinguishes it from action siblings like trooth_connection_connect and trooth_stack_fix.

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

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

Explicitly routes the agent onward: 'fix resync' goes to trooth_stack_fix, 'fix new_credential' goes to trooth_connection_connect with a read-only credential, and AWS cases go to aws_setup. This names alternatives and the conditions that select them rather than leaving routing 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 cover the safety profile (not read-only, not destructive, idempotent, closed-world), and the description adds genuinely new behavior: the request runs without an approval step, one request per provider with re-asking refreshing it, and the workspace is derived from sign-in or key rather than an argument. That last point is valuable because it tells the agent not to attempt a workspace parameter. The garbled auth sentence weakens the delivery slightly.

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?

Most of the text is dense and earns its place, but the opening sentence is an ungrammatical fragment ('With your trooth.co sign-in, or the workspace's agent key with the stack area (Bearer tra_...).') that forces the reader to reconstruct the meaning. The core action is also buried after the auth clause rather than front-loaded.

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

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

For a two-parameter write tool with an output schema, the description covers authentication, workspace resolution, approval behavior, idempotency, and the follow-up tool. Nothing essential to invoking it correctly is missing, though the credential wording could be stated more plainly.

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 parameters are already documented, including that provider accepts a name or https address and that note is optional. The description restates the same meaning ('by name or https address, with an optional note on what to read') without adding format rules or edge cases. 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?

The description states a specific verb and resource ('Request a connector on trooth.co/dashboard/connect') and scopes it to providers Connect has no connector for, which separates it from trooth_connection_connect. It also names trooth_evidence_add as the sibling for the adjacent task. The opening sentence is a sentence fragment about credentials, which slightly muddies an otherwise clear purpose statement.

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

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

It gives an explicit use condition ('for a provider Connect has no connector for') and points at the alternative path for evidence with trooth_evidence_add. It also states the repeat behavior ('asking again refreshes it'), which tells the agent not to look for an update tool. It stops short of saying what to do if Connect already has a connector, leaving that 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?

Beyond the annotations, the description discloses the human-approval gate, the approval_required intermediate state, the two-call retrieval pattern, and that the token is shown only once — all high-value behavioral facts for a write tool. Two blemishes: the 'call again with the same arguments' instruction sits in tension with idempotentHint=false, and the final sentence about payments/confidential data/sign-ins restates authority rules in a way that does not map onto this tool's actual data_class enum (public/internal).

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?

Only three sentences, but the first is ungrammatical and missing its verb, so the reader must reconstruct the auth requirement, and the third sentence is a confusing coda that does not obviously apply to this endpoint. The most important fact — create then re-call to get the one-time token — is buried in the middle rather than front-loaded.

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

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

For a 7-parameter mutation behind human approval, the description covers the essentials an agent needs: auth scope, the approval wait, the retry-to-retrieve pattern, and the one-time token. An output schema exists, so return shape need not be explained, and the remaining gaps (what happens on denial, how to check status via trooth_delegations) are minor.

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

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

Schema description coverage is 100%, so the schema already explains every parameter, making 3 the baseline. The description adds no parameter-level detail (no hint at role examples, expiry limits, or why data_class is restricted), and its mention of 'confidential or restricted data' actively conflicts with the public/internal enum, so it does not compensate with useful 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 middle sentence states the core action and scope: 'Asks for one data-sharing delegation,' which is clearly distinct from trooth_delegations (list) and trooth_delegation_revoke. However, the opening sentence ('With the workspace's agent key with the settings area') is syntactically broken, and the closing sentence about payments, confidential/restricted data, and sign-ins muddies what the tool actually does versus what it merely notes.

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 genuinely useful procedural guidance — expect status approval_required, then call again with the same arguments to obtain the delegation and its token. It also states the auth prerequisite (agent key with settings scope, Bearer tra_...). What is missing is any routing advice relative to siblings: no mention of when to use trooth_delegations to check status or trooth_delegation_revoke to undo one.

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

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

Adds substantial context beyond the annotations: authentication can be a trooth.co sign-in or an agent key with the settings area (Bearer tra_...), and the workspace is derived from credentials rather than an argument. It also discloses cascade behavior (all unredeemed references issued by the delegation are revoked), that a signed receipt is produced, and it independently confirms the idempotentHint ('calling it again changes nothing').

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?

Compact, with auth and scope front-loaded and no filler sentences. However, the opening sentence is an elliptical fragment with no main verb ('With your trooth.co sign-in, or the workspace's agent key...'), which costs the reader a re-read before the action is clear.

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 mutation with an output schema, everything an agent needs is present: auth mode, workspace resolution, cascade scope, receipt on success, and idempotency. Return-value details are rightly omitted since an output schema exists.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented with its pattern and source. The description only reinforces provenance ('as trooth_delegations gives it'), which the schema already states, adding no format or validation detail beyond it — baseline 3 for a fully documented single parameter.

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 ('Revokes') and a precisely scoped resource: one delegation plus every unredeemed reference it issued. It also names the sibling that supplies the id (trooth_delegations), which distinguishes it from trooth_delegation_create. The leading fragment about sign-in slightly muddies the opening, so the purpose lands a beat later than ideal.

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

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

Implies the prerequisite flow by saying the id comes 'as trooth_delegations gives it,' so an agent can infer it must list before revoking. It names no alternative tool and gives no explicit when-not-to-revoke condition (e.g., create-then-revoke vs. direct revocation paths), leaving the routing decision partly to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description nonetheless adds real behavioral context: authentication route, workspace derivation from the credential, newest-first ordering, cursor paging, and the full field set returned. It does not mention rate limits or page-size defaults, but those are partly 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?

The body is dense and largely front-loaded (auth, then purpose, then paging, then read-only), and little is redundant. But the opening is a sentence fragment — "With your trooth.co sign-in, or the workspace's agent key with the settings area (Bearer tra_...)." — which costs readability right where the agent looks first.

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-param, zero-required list tool with an output schema and full annotation coverage, this is close to complete: auth path, scoping source, ordering, pagination, returned fields and read-only status are all stated. Only sibling disambiguation 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 limit and cursor are already documented with bounds and defaults — a baseline 3. The description goes beyond the schema by asserting that the workspace is never an argument, which tells the agent not to attempt a scope parameter, and by noting cursor paging behaviour that ties the two optional params together.

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 ("Lists Agent authority's delegations") and enumerates the returned fields — key thumbprint, role, company scope, permissions, expiry, revocation state, receipts — so the agent knows exactly what it gets back. It does not explicitly contrast itself with the near siblings trooth_agent_keys_list or trooth_delegation_create/revoke, leaving that distinction 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?

It gives useful activation context — sign-in or workspace agent key, Bearer tra_..., settings-area scope — and states that the workspace is derived from auth rather than an argument, which prevents a common mis-call. However, it never says when to prefer this over trooth_agent_keys_list or when to follow up with trooth_delegation_revoke/create, so usage versus alternatives is only implied by the read-only listing nature.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), it discloses the two-phase state model — the new version waits and the Trust Center keeps showing the current one until publish — plus the exact auth scopes required and the human-approval round trip with a re-call instruction. That is precisely the kind of state, permission, and multi-step behavior an agent cannot infer from the schema or annotations.

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

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

Nothing is wasted, but the structure is poor: it opens with a sentence fragment about authentication before saying what the tool does, then packs staging, publishing, and the approval loop into one long colon-chained sentence. Front-loading the action and moving auth/approval into a second sentence would improve it without adding length.

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 moderately complex staged-mutation tool with an output schema (so return values need no explanation), it covers auth, both source types, the waiting state, and the approval-and-retry requirement. The remaining gap is edge-case behavior: an already-staged version, supplying neither url nor evidence_id, or what state the document is left in if approval is denied.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: url and evidence_id are presented as alternatives ('as an https url or an Evidence Vault file (evidence_id)') and publish is framed as the gate that promotes the waiting version, including who may set it. It still leaves unclear whether both url and evidence_id can be supplied together or what happens if neither is.

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: it keeps a newer version of one Trust Center document (document_id), sourced from an https url or an Evidence Vault file, staged until publish. That distinguishes it from pure evidence tools like trooth_evidence_add and from trooth_documents_stale, but it never names a sibling explicitly, and the fragmented opening clause pushes the actual purpose into the second half of the sentence.

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 context: you need a sign-in or an agent key with profile:write, publish=true requires profile:publish plus a person's approval, and you must call again once approved. What's absent is an explicit 'don't use this when…' — e.g. whether to use trooth_evidence_add first to stage a file into the Vault before calling this, or how this differs from updating the document record itself.

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

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

Beyond the annotations (which already declare read-only, idempotent, non-destructive), it discloses authentication requirements (trooth.co sign-in or a tra_ agent key with profile:read as Bearer), that the workspace is derived from auth and 'never an argument', ordering, and per-item returned fields (days unchanged and the pending next version). That is substantive behavioral context the annotations cannot convey.

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

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

Front-loaded with the auth/scope prerequisite, then the operation, then the alternative and pagination. Dense and somewhat run-on with parentheticals, but every clause carries information an agent needs; nothing is filler.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, the description supplies everything remaining: auth path, implicit workspace scoping, ordering, pagination contract, and how results tie to the stale-document rule. No gaps an agent would need to guess at.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the linkage that cursor/next_cursor drive paging and that a cursor must be sent with the same other arguments — meaning that goes slightly beyond the schema's field-level text. Limit semantics are left entirely to the schema, which is fine.

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 (lists Trust Center documents unchanged for 365 days), plus ordering (oldest first) and the triggering rule (document.stale). It also names the sibling to use instead for the mutation path, trooth_document_replace, so an agent can distinguish it 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?

Clear about the condition that selects this tool (documents untouched for a year, i.e. stale candidates) and routes remediation to trooth_document_replace. It does not explicitly state when not to use it, e.g. for recently updated documents, but the selection criterion 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 destructiveHint=false, so the safety profile is covered. Beyond that, the description adds real context: the workspace is derived from sign-in or agent key and never from an argument, auth accepts a Bearer tra_ key, results are newest-first, and each event carries the payload that was sent to alert destinations. 'Read only' merely restates the annotation.

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 dense and mostly earns its place, but the opening is a verbless fragment about authentication rather than a statement of purpose, and the parenthetical '(Bearer tra_...)' is awkwardly placed mid-context. The actual function of the tool only appears in the second sentence, so the description is not front-loaded on what the agent most 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?

An output schema exists, so return shape and next_cursor need not be re-explained, and the description covers auth modes, workspace scoping, ordering, event taxonomy and pagination. The remaining gap is disambiguation from sibling read tools that expose adjacent event data, which for a tool in this crowded family is worth one sentence.

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 limit, types and cursor are already fully documented with ranges and examples. The description adds only the pairing rule that cursor comes from next_cursor of the previous answer, which is already present in the schema text. 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?

The description states a specific verb and resource ('Lists the workspace's events newest first') and enumerates the concrete event types (connection.lost, approval.requested, document.stale, key.expiring), so the agent knows exactly what it gets back. It stops short of differentiating this from close siblings like trooth_audit_events or trooth_notifications_list, which also return workspace event-like records.

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