Subo

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds the append semantics and the mandatory pre-read step, which is useful behavioral context, but says nothing about failure modes, duplicate blocks, or how the mutation affects existing script content.

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

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

Two tight sentences, zero filler, with the core action front-loaded and the prerequisite immediately following. Every sentence earns its place.

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

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

No output schema exists, so return values need not be explained, and the guide reference is a reasonable strategy for the unguessable vocabulary. However, for a 29-parameter mutation tool, deferring essentially all parameter meaning to an external resource leaves the description thin relative to the tool's complexity.

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

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

Schema description coverage is only 3% across 29 parameters, so the description carries the burden — yet it explains no individual parameter. It does acknowledge that block type names, section names, and piping rules are unguessable and points to the authoring guide, which is a partial mitigation for the `type`/`section` params, but the vast majority of parameters remain semantically opaque.

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 ('Append one block to a project's script'), which cleanly separates it from update_block, delete_block, and replace_script by the 'append' action. It stops short of naming any sibling explicitly, so a reader must infer the distinction, keeping it at a 4 rather than 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?

It states a clear prerequisite — read the subo://guide/authoring resource before writing — and explains why (block types, section names, and piping rules are unguessable). That is solid when-to-use context, but there is no guidance on when to prefer this over replace_script, plan_script, or generate_script, so no exclusions are offered.

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

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

Annotations cover safety flags (write, not idempotent, not destructive), and the description adds real context beyond them: what is copied (project + script), what is excluded (responses), and the resulting state (new project is inactive until opened). It stops short of noting that repeated calls produce distinct projects, but the annotations already flag non-idempotency.

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 core action, then the two most decision-relevant qualifications (responses excluded, project inactive). No filler sentences.

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

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

With no output schema, the description adequately conveys the resulting artifact and its inactive state for a two-parameter clone operation. The main gap is the undocumented optional name argument and what the new project's identity looks like.

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

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

Schema coverage is 50%: project_id carries a description while the optional 'name' parameter has none. The tool description says nothing about parameters at all, so it fails to compensate for the undocumented name argument (e.g., that omitting it reuses/defaults the source name).

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

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

States a specific verb and resource ('Copy a project and its script into a new inactive project') and clarifies scope by noting responses are not copied, which separates it from clone_template (templates) in practice. It never names a sibling explicitly, so differentiation relies on inference from the resource named.

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

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

'The copy reaches nobody until you open it' implies the clone-then-open workflow and hints at open_project as the follow-up, but there is no explicit when-to-use statement, no reference to alternatives like create_project, and no prerequisites named.

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

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

The annotations already declare readOnlyHint=false and idempotentHint=false, so the write/non-idempotent nature is covered structurally. The description adds genuinely new behavioral context: the result is an inert, unpublished project that 'reaches nobody' until opened, which is important state information an agent would otherwise have to guess.

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

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

Two tight sentences, front-loaded with the core action, and the second sentence carries distinct, non-redundant information about the inactive state. Nothing is wasted.

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

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

For a two-parameter mutation tool with no output schema, the description covers the lifecycle behavior well but omits the return value (e.g., new project id) and says nothing about the optional name parameter. An agent can invoke it with template_id alone, so it is minimally viable but has clear gaps.

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

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

Schema coverage is only 50%: template_id is documented in the schema ('from list_templates'), but the 'name' parameter has no description anywhere. The description adds no parameter-level detail at all — it doesn't explain that name sets the new project's title or what happens if name is omitted (default null). It fails to compensate for the coverage gap.

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

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

The description gives a specific verb+resource: 'Create a project from a template,' which is clear and distinguishable from plain create_project by the 'from a template' qualifier. It does not explicitly contrast itself with the sibling clone_project, so an agent must infer that this one uses a template rather than an existing project.

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

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

It states a useful sequencing fact — the cloned project stays inactive until open_project — which implicitly tells the agent what to do next. However, it never says when to prefer clone_template over create_project or clone_project, so selection guidance is only implied.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false; the description goes beyond them by spelling out the user-visible consequences (members see it close, can no longer answer, results freeze) and confirming non-destruction ('Existing responses are kept'). It stops short of covering reversibility or repeated-call/idempotency behavior, which the idempotentHint=false annotation leaves unaddressed.

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

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

Three short sentences with the core effect front-loaded and zero redundancy. Every clause carries information: the state change, the member-facing impact, and the data-retention guarantee.

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

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

For a single-parameter state-change tool with no output schema, the description covers the effect and data retention well. The remaining gap is that it never says whether the closure is reversible (e.g., via open_project) or what happens if called on an already-closed project.

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

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

Only one parameter (project_id) at 100% schema description coverage, so the schema already documents it fully, including its source (list_projects or create_project). The description adds no extra parameter meaning, which is the expected baseline 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 ('Stop a project from accepting new responses') and immediately distinguishes the effect from a delete by noting existing responses are kept and results freeze. An agent can tell this apart from delete_project and open_project without opening any schema.

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

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

The effect is clear, so when to use it is implied, but it never explicitly names the alternative (open_project to reverse, delete_project for removal) or states the condition that selects this over them. Adequate but leaves 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 declare non-read-only, non-destructive, non-idempotent, closed-world creation; the description adds genuinely new behavior: the created project reaches nobody until opened, the AI-draft path spends community credits, the response carries draft.author_notes to review, and ordering via delivery.opening.time is self-executing. It omits anything about permissions/errors, hence 4 rather than 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?

Dense but front-loaded: creation semantics first, activation/scheduling second, script-sourcing third, parameter caveats last. Every sentence adds signal; the only cost is length, which is proportionate to a 21-parameter tool.

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 large, no-output-schema creation tool it covers lifecycle, script sourcing, credit cost, privacy default and the required pre-read of subo://guide/authoring. The main gap is the large set of untouched optional parameters, but the highest-risk decisions are all addressed.

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

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

Schema description coverage is 0% across 21 parameters, so the description carries the burden — and it does cover the decision-critical ones: the three mutually exclusive script sources, privacy_mode's inheritance default and the anonymity risk, and delivery.opening.time. Many remaining params (plan, facts, answers, rewards, settings, presentation, quality, etc.) are still undocumented in both places, so it compensates well but not fully.

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

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

States a specific verb and resource ('Create a survey or poll') and immediately scopes it against siblings: it names open_project for activation, points at generate_script for draft inputs, and explains source_project_id as the fork alternative to clone-style flows. An agent can place this tool precisely among the 40+ siblings.

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

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

Gives explicit when/when-not conditions: the project is inert until open_project or a scheduled delivery.opening.time, the human should confirm before scheduling, and the script must come from exactly one of three mutually exclusive sources. This is the rare case 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?

The annotations already declare readOnlyHint=false, destructiveHint=false, and non-idempotence. The description adds critical operational behavior: the signing secret is returned once and must be handed to a human immediately, and the URL must be HTTPS on a public address. These are high-value disclosures beyond the structured 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?

Four tight sentences with no waste. The one-time secret warning and URL validation are front-loaded and easy for an agent to act on.

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?

The description covers the most dangerous behavioral detail (one-time secret) and URL validation, which is important given the lack of an output schema. However, with 0% schema description coverage it omits what the events array should contain and what name does, leaving the creation payload under-specified.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It clarifies the url constraint (HTTPS, public address) but says nothing about the required events array or the optional name parameter, leaving most parameter semantics undocumented.

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

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

The description states a specific verb and resource: registering an HTTPS endpoint to receive events. It clearly distinguishes creation from reading or deletion, but it does not explicitly differentiate itself from siblings like update_webhook, rotate_webhook_secret, or delete_webhook.

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 'Register an HTTPS endpoint to receive events' and the URL constraints, but the description never states when to choose this tool over update_webhook, rotate_webhook_secret, or test_webhook. No alternatives or exclusions are named.

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, but the description adds substantial context beyond them: skip logic and piped variables become invalid, and failures surface at runtime rather than at deletion time. That downstream-effect disclosure is exactly what a destructive tool needs.

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

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

Three tightly packed sentences with zero filler; the destructive warning leads and the remediation step closes. Every sentence carries unique 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?

Covers safety, side effects, failure timing, and the required follow-up action. Nothing an agent needs in order to call this destructive tool safely is missing, even without an output schema.

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

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

Schema description coverage is 100% – both block_id and project_id are documented with sources ('from get_script', 'from list_projects'). The description adds no parameter detail beyond 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?

States a specific verb (Delete) and resource (one block from a script), and crucially scopes it to a single block, distinguishing it from sibling mutators like delete_project or delete_response.

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

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

Gives a clear post-condition action ('Always run validate_script afterwards') and warns of the failure mode, but does not contrast directly with update_block as an alternative for minor edits.

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=false, but the description adds real substance beyond them: the deletion is a cascade covering responses, there is no undo, and no export is possible afterward. Those consequences are not derivable from the annotation flags and directly inform agent 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 short sentences, front-loaded with the 'Destructive:' signal, then the irreversibility, then the mitigation. No filler and the most important information comes 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 single-parameter destructive tool with a well-covered schema and no output schema, everything an agent needs to decide and act correctly is present: severity, cascade scope, irreversibility, and a pre-call caution.

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 project_id parameter is already documented with its provenance ('from list_projects or create_project'). The description adds no parameter-level detail, 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 ('Permanently delete a project') and adds scope by naming the cascade target ('and its responses'). The word 'permanently' plus the cascade clause distinguishes it from sibling operations like close_project or delete_block without opening any schema.

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

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

Gives a clear conditional guideline: 'Read the responses first if they matter.' That tells the agent when to hesitate before calling. It stops short of naming alternatives (e.g., close_project for a reversible option, get_project/list_responses as the read path), which would be the 5-level answer.

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, readOnlyHint=false, and idempotentHint=false. The description's 'Permanently... There is no undo' reinforces the destructive profile but adds little that the flags don't already convey, and says nothing about auth needs or effects on related data.

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

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

Two short sentences, with the destructive nature front-loaded in the first clause. Nothing is wasted and the critical warning comes 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 simple two-parameter destructive operation, the description plus annotations plus a fully documented schema cover what an agent needs. The only shortfall is no explicit tie-breaker against the plural delete_responses sibling.

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 only two required params, and the schema explains provenance for each (list_projects/create_project, list_responses). The description adds no parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('delete one response') with the word 'Permanently' signaling irreversibility. It does not explicitly distinguish itself from the sibling delete_responses, though 'one response' hints at singular vs bulk scope.

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

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

No guidance on when to choose this over delete_responses (the bulk sibling) or get_response/update alternatives. The only routing signal is the implicit singular 'one response', which is left for the agent to infer.

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=false, but the description adds genuinely new behavioral facts: irreversibility ("There is no undo") and a cascade effect ("Analysis and results go with them"). It does not cover authorization requirements or behavior on an empty/already-empty project, so it is good rather than 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 with the severity marker front-loaded, then the action, then the consequence. No filler and nothing buried.

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

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

For a one-parameter destructive tool with rich annotations and no output schema, the description supplies the essentials: what is destroyed, that it is irreversible, and what collateral data goes with it. It could still note whether the project itself survives or how to recover, but nothing critical for a correct call is missing.

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

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

Schema description coverage is 100% and the single project_id parameter is fully documented in the schema (including its source via list_projects/create_project). The description adds no further meaning about the parameter, 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 (delete) plus resource and scope (every response to a project), which implicitly separates it from the singular sibling delete_response. It stops short of naming the sibling or stating the bulk-vs-single distinction explicitly, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance and no mention of the obvious alternative, delete_response, for removing a single response. The only context given is a destructiveness warning, which is a caution rather than selection 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered; the description adds genuinely new context by disclosing that delivery history is destroyed along with the endpoint and that the receiving system loses events silently, with no other warning.

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

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

Two tight sentences, front-loaded with the 'Destructive:' signal, and every clause earns its place by adding scope or consequence rather than restating the title.

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

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

For a single-parameter delete with full annotation coverage and no output schema, the description covers what is deleted, the collateral loss of history, and the external effect. Only minor gaps remain, such as whether the deletion is immediate/permanent or requires any confirmation.

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 webhook_id parameter is fully documented there (including its provenance from list_webhooks), so the description adds nothing on parameters; the baseline of 3 applies when the schema carries the full burden.

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

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

States a specific verb and resource ('Delete a webhook endpoint') and goes further by naming the collateral object ('its delivery history'), which cleanly separates it from sibling mutations like update_webhook, delete_block, and delete_project.

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

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

Usage is only implied: the consequence clause ('The receiving system stops getting events') suggests when an agent would want this, but there is no explicit when-to-use, no when-not-to, and no pointer to alternatives such as update_webhook or rotating the secret instead.

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

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

Goes well beyond the annotations: it discloses the downstream effect (open projects gated on this source lose their gate) and the practical irreversibility (reconnecting requires a human browser sign-in no tool can perform). This is exactly the consequence-level detail an agent needs before invoking a destructive operation.

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

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

Four compact sentences, front-loaded with the destructive warning, then consequence, then irreversibility, then prerequisite. No filler and every sentence carries actionable information.

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

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

For a one-parameter destructive tool with no output schema and annotations already covering the safety profile, the description supplies everything else an agent needs: consequences, reversibility, and a pre-check. 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% and the single parameter is documented in the schema ("Audience source id, from list_sources"). The description adds no syntactic or format detail 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?

Specific verb (Disconnect) plus resource (verified-audience source), with scope and consequence stated. It clearly distinguishes itself from siblings like list_sources/list_projects, which are referenced as the inspection tools rather than the disconnecting tool.

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

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

"Check list_projects first" gives an explicit prerequisite/context for use, and the reconnect caveat warns of the commitment. It does not spell out when NOT to use it or name a true alternative, keeping it just short of a 5.

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

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

Goes well past the annotations by disclosing real cost behavior ('spends the community's AI credits, every model call, repairs included'), the non-persistent return contract, the mapping to `scoring_enabled`, and a caveat that model knowledge has a cutoff. The annotations only say it is a non-idempotent, non-destructive write; the description adds the spend, the chaining contract, and the author_notes warning.

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

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

Front-loaded with the core action, then compact, information-dense clauses about cost, return shape and chaining; nearly every sentence earns its place. It reads slightly cramped, packing four distinct directives into one paragraph without separators, which costs a little scannability.

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, no-output-schema tool the description covers the workflow essentials (what comes back, where it goes next, the credit cost), but leaves the majority of the input surface undocumented. An agent knows what the tool does and does not do, yet would be guessing on quality, type and question_count.

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

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

Schema description coverage is 0% across 10 parameters, and the description only adds meaning for two of them: `intent` (implied by 'plain-language goal') and `facts` ('put anything current... the model's knowledge has a cutoff'). Plan, type, quality, answers, question_count, language, session_id and admin_language — including two enums — are left entirely unexplained anywhere.

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

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

States a specific verb+resource ('Draft a script from a plain-language goal') and immediately marks the boundary that separates it from create_project/replace_script: it returns blocks without creating a project. An agent can distinguish it from plan_script and validate_script from the description 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?

Explicitly names the downstream tools (create_project, replace_script) and the payload to forward, plus a clear rule to surface author_notes to the person before opening a project. It does not, however, say when to choose generate_script over the sibling plan_script or when a draft should be validated first, so routing among the script tools is only partially resolved.

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 meaningful non-annotation context: aggregates are always current while summaries are conditional, and the polling relationship to trigger_analysis. It stops short of describing pagination or response 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?

Purpose is front-loaded in the first sentence, and each subsequent sentence adds distinct value (freshness, polling trigger, count disambiguation). Slightly dense but nothing is wasted.

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

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

With no output schema, the description usefully pre-explains the two return counts and their differing units, which is exactly what an agent needs to interpret results. It omits response structure and pagination details, but the core output semantics are covered.

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

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

Schema description coverage is 100% with a single project_id parameter, so the schema already carries the semantics. The description adds no parameter-specific meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Get a project's aggregates and AI summaries') and immediately distinguishes the two output kinds. It also names the sibling trigger_analysis, so an agent can place it in the workflow without opening other schemas.

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

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

Gives clear context: 'poll this after trigger_analysis' and notes AI summaries exist only for blocks that have been analyzed. It does not state explicit when-not-to-use conditions, but the trigger relationship is a solid usage signal.

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, not open-world), so the description is free to add new value; it does so by enumerating the returned content (name, tier, settings groups, usage). It stops short of auth/scope or failure-mode context, and the return description 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 tight sentences: purpose first, payload second, scope constraint last. Every sentence earns its place with no filler.

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

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

With no output schema, the description usefully sketches the return shape, which is the main missing structured signal for this tool. It leaves the 'expand' behavior unaddressed, but the essentials for correct invocation are present.

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

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

The single 'expand' parameter is fully documented in the schema (100% coverage, with an example), so the description adds nothing about it. Baseline 3 applies when the schema already carries parameter 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?

States a specific verb and resource ('Get the community') and scopes it precisely to the connection-bound community. It is clearly distinct from the many get_*/list_* siblings, though it never names a sibling to route against.

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?

Tells the agent the operative constraint for invoking it: the community is fixed by the connection and no other community is reachable. That implicitly rules out passing an ID or expecting multi-community access, but there is no explicit 'use this when...' or alternative named.

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 readOnly/idempotent/openWorld, so the bar is lower, and the description adds genuine context: it distinguishes derived_access (from platform roles) vs granted_access (human-granted in Subo) and states no mutation is possible here. It does not discuss return format, which is left unaddressed.

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 focused sentences: purpose first, then field disambiguation, then scope boundary. Every sentence carries information, though the two backticked field names make the middle sentence slightly dense.

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

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

With no output schema, the description carries the return-value burden and does a fair job naming XP, accomplishments, and the two access fields. It is complete enough to call correctly, though it doesn't hint at shape or structure of the returned member.

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 member_id param is documented with its source ('from list_members'). The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one member') and names what it returns (XP, accomplishments, access). The singular 'one member' implicitly distinguishes it from the sibling list_members, so an agent can route correctly 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?

Clearly scoped to reading a single member and explicitly rules out mutation ('Changing either is not available here'), routing the agent elsewhere for edits. It does not name the alternative tools (e.g. modify_xp, modify_accomplishments), so it stops short of explicit alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description earns credit for adding a genuinely new behavioral fact: delivery.share_url is the respondent-facing link and is null for Discord-answered projects. The 'share it as given' instruction warns against mutating the URL, useful for an agent. No return-shape or pagination detail beyond that.

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

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

Two sentences, no filler. The core purpose leads, and the share_url caveat follows only because it prevents a concrete misuse.

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 single-record fetch with no output schema, the description covers the purpose plus one non-obvious field semantic and its null condition. It stops short of describing response structure, but annotations and the complete param schema carry the rest.

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 (expand, project_id) are already documented in the schema, with expand's 'script' meaning fully spelled out. The description adds nothing about parameters, 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 ('Get one project') and enumerates what comes back — delivery, rewards, settings. The singular 'one project' implicitly separates it from list_projects, though no sibling is named explicitly.

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

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

Usage is implied rather than stated: the schema notes project_id comes from list_projects or create_project, and the description's advice about share_url hints at the respondent-sharing workflow. There is no explicit when-to-use or when-not statement and no named alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety behavior is covered. The description adds that the returned entity includes answers and scores, which is useful content context, but says nothing about missing/invalid IDs or error 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?

A single front-loaded sentence with no redundant or filler content. Every clause (verb, resource, payload) earns its place.

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

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

For a simple two-parameter getter with no output schema, the description supplies the key return-content hint (answers and scores) and annotations carry the safety profile. It is nearly complete, though error/not-found behavior is not mentioned.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema with their provenance (list_projects and list_responses). The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ('Get one response') and clarifies the payload ('with its answers and scores'). It implies the singular retrieval counterpart to the sibling list_responses, but does not name that sibling explicitly to differentiate.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives such as list_responses or get_analysis named. The only usage signal is the implied one of fetching a single response rather than a list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety and idempotency are covered. The description adds that blocks are returned in order, which is a useful behavioral trait beyond the annotations, but it does not cover output format, pagination, or the effect of the expand parameter.

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

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

The description is a single, front-loaded sentence that directly states the tool's action and return. Every word earns its place with no redundancy or filler.

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

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

For a simple read-only tool with complete schema coverage and annotations, the description is largely complete: it says what is returned (blocks in order). It does not mention the optional expand parameter, but that is well described in the schema, so the gap is minor.

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

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

Schema description coverage is 100%, with both project_id and expand fully documented in the schema. The description adds no additional meaning about parameters, so the baseline of 3 applies.

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

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

The description states a clear verb ('Get') and resource ('a project's blocks in order'), so an agent knows it retrieves ordered blocks. It does not explicitly differentiate from sibling script tools like generate_script or validate_script, which keeps it from a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as generate_script, replace_script, or validate_script. The read-only nature is implied by 'Get' and annotations, but no explicit usage context or exclusions are provided.

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 readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so the safety profile is fully covered. The description adds that the response includes the 'full script', which is useful return-content context beyond the annotations. That is meaningful added value, but not rich behavioral 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?

One short sentence, front-loaded with the verb and resource, with zero waste.

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

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

For a simple read-only getter with full schema coverage and annotations covering safety, the description is nearly complete. The only minor gap is no guidance on when to prefer this over list_templates or get_script, but with an output-less schema and straightforward purpose, it is adequate.

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%; both parameters are documented in the schema, including a reference to list_templates for template_id. The description adds nothing parameter-specific, so baseline 3 applies.

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

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

States a specific verb+resource: 'Get one template with its full script.' Clear and distinct from list_templates. However, it doesn't differentiate from sibling get_script or explain how it relates to list_templates, though the schema param description does reference list_templates.

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

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

No guidance on when to use this versus alternatives like list_templates or get_script. The description is a single declarative sentence with no context for selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, not open-world), but the description adds a genuinely useful behavioral fact beyond them: the signing secret is deliberately omitted and only surfaced at creation. That prevents an agent from expecting the secret or trying to retrieve it. It stops short of describing the returned fields or error 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?

Two compact sentences, zero filler, with the core action front-loaded and the secret caveat second. Every clause earns its place.

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

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

For a simple single-parameter read tool with full annotation coverage and no output schema, the description is nearly sufficient; the secret-omission note covers the main surprise. Naming what the response contains or how missing IDs are handled would close the remaining 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 description coverage is 100% and the single parameter (webhook_id) is documented there with its source (list_webhooks). The description adds no format or syntax detail beyond 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?

States a specific verb and resource ('Get one webhook endpoint'), and 'one' signals single-item retrieval as opposed to the list_webhooks sibling. It does not name the sibling explicitly, so differentiation is implied 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?

No when-to-use guidance, no prerequisites, and no alternatives named in the description. The only routing hint ('from list_webhooks') lives in the schema's parameter description, not the tool description.

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 openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact, the 'newest first' ordering, but says nothing about pagination behavior or entry contents.

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

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

A single front-loaded sentence with zero filler; the resource and its ordering are stated immediately with no redundancy.

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

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

For a simple read-only list tool with full schema coverage and safety annotations, the description is adequate but thin: it omits pagination behavior and, with no output schema, gives no hint of what an XP ledger entry contains.

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

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

Schema description coverage is 100% with three documented parameters, so the baseline is 3. The description adds no syntax or format detail for member_id, page or per_page beyond what the schema already states.

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

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

States a specific verb (List) and resource (a member's XP ledger entries), with the scope narrowed to a single member. It is clearly distinguishable from write siblings like modify_xp, but it never names an alternative explicitly.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as get_member or modify_xp. Usage is only implied by the tool name and the word 'List'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered. The description adds essentially no behavioral context beyond that, and the phrase 'a project can use' hints at project scoping despite there being no project parameter.

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

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

A single short sentence, front-loaded with the verb and resource. Minimal but not wasteful; the trailing 'a project can use' clause adds slight ambiguity for no clear benefit.

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

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

For a no-param, no-output-schema list tool, the description should ideally indicate what the return contains (names, ids, counts). It leaves the caller unsure what an 'interviewer persona' record looks like, which is a real gap when no output schema exists.

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

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

Zero parameters, so there is nothing for the description to disambiguate. Baseline 4 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 clear verb (list) and resource (interviewer personas), which is distinguishable from sibling list tools like list_members or list_themes. It doesn't explicitly differentiate itself from those siblings, so it stops short of a 5.

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

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

The description implies usage (fetch the available interviewer personas) but gives no when-to-use conditions, prerequisites, or alternative tools. Nothing tells the agent whether this should be called before another 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, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds nothing behavioral beyond that: no pagination semantics, no note that search/platform_id narrow results, no indication of result ordering or size.

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

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

A single short sentence with the resource scoping front-loaded and no filler. It is appropriately sized, though its brevity borders on under-specification rather than disciplined conciseness.

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 100% schema coverage and complete annotations, an agent can call this correctly, so nothing critical is missing. But with no output schema and no description of return shape, ordering, or pagination behavior, the definition is only minimally complete for a list endpoint.

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 page, search, per_page, and platform_id are each documented in the schema (including the Discord snowflake lookup). The description adds no parameter meaning of its own, which is the baseline 3 when the schema carries the full burden.

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

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

States a specific verb (List) and resource (this community's members), so the core operation is unambiguous. However, it offers no differentiation from near-siblings like get_member (singular) or list_interviewers, so the agent must infer the boundary from the name alone.

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

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

The description gives no when-to-use guidance, no mention of filtering options, and no pointer to alternatives such as get_member for a single member. The only implied guidance comes from the verb 'list' versus 'get', which the agent must supply 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered elsewhere. The description adds nothing beyond that: it says nothing about pagination, default page size, whether all projects are returned at once, or the shape of the result, which is the value a description should add when annotations exist.

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

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

One short sentence, front-loaded with the verb and resource, with no filler. It is efficient, though the extreme brevity edges toward under-specification rather than ideal sizing for a seven-parameter listing tool.

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

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

There is no output schema, seven optional parameters, and pagination behavior that the description never addresses. An agent cannot tell from the description whether results are paginated by default, how filtering interacts, or what a project record contains, so the definition is incomplete for a tool of this complexity.

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

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

Schema description coverage is 100%, so all seven parameters (page, type, expand, status, per_page, created_after, created_before) are already documented in the schema. The description contributes no additional meaning about filtering or pagination semantics, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List ... projects') and scopes it to 'this community's', so an agent knows it retrieves a collection rather than a single item. It does not, however, distinguish itself from siblings like get_project or list_templates, so it lands at a clear-but-undifferentiated 4.

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

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

There is no when-to-use guidance, no mention of alternatives (get_project for a single project, create_project for creation), and no indication of prerequisites. The agent is left to infer usage purely from the name.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-openWorld), and the description adds genuinely non-obvious behavior beyond them: identity fields are null on anonymous projects, respondent filters fail with a 400, and answer text is untrusted community content. That is exactly the kind of surprising-failure-mode and safety context 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?

Three tight sentences with the core purpose front-loaded, followed by the two highest-value caveats. Every sentence earns its place and nothing is redundant.

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 paginated list tool with no output schema, the description covers privacy semantics and the filter failure mode well. It omits the return shape (a collection of responses) and pagination behavior, which the absent output schema leaves undocumented, so a small gap remains.

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 page, user_id, provider, platform_id, session_number, and project_id are all documented in the schema itself. The description references "respondent filters" generically but adds no format, default, or interaction detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ("List a project's responses"), which cleanly separates it from the singular get_response and the delete_response(s) siblings. It does not explicitly name an alternative tool or state when not to use it, so it stops short of a 5.

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

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

Usage is implied by the listing scope, and the note that respondent filters return 400 on anonymous projects is operationally useful. However, there is no explicit when-to-use guidance or routing to siblings like get_response for a single record, leaving the agent to infer.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description usefully adds that sources are external providers and that new connections happen outside tooling via browser sign-in. It could add more about return ordering/shape, but it adds real context beyond the annotations.

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

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

Three tight sentences, each earning its place: the list action, the definition of a source, and the down-stream usage plus the boundary about connecting. Purpose is front-loaded with no filler.

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

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

For a zero-parameter, no-output-schema list tool with annotations covering the safety profile, the description supplies everything an agent needs: what is returned, where the ids are consumed, and why no connect operation appears in the toolset.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool is 4. No param semantics are missing.

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

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

States a specific verb+resource ('List the connected verified-audience sources') and immediately defines what a source is (Discord, YouTube, Twitch, Steam providers that a project can gate audience on). This clearly separates it from siblings like disconnect_source and open_project.

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

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

Explains the downstream purpose: the returned ids go in `delivery.audience.verified_source_ids` when opening a project, and notes that connecting a new source requires browser sign-in so no such tool exists here. It gives clear context but never names a sibling (e.g., disconnect_source) for the removal case.

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 openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral detail — the catalog contains only public templates — but says nothing about result size, pagination, or filtering behavior despite five filter parameters.

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 and front-loaded, with the core action in the first sentence and the browsable URL as a compact trailing pointer. 'Templates are ready-made projects' is mild filler but does ground the term.

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

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

For a read-only list tool with no output schema and a fully documented schema, the description is adequate but thin. It omits what a result looks like and how filtering interacts, which an agent choosing between five optional filters would benefit from.

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 filters (tag, type, locale, search, category) are already documented in the schema, including the 'convo or poll' values for type. The description adds no additional parameter meaning; 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 (List) and resource (the public template catalog), which clearly separates it from get_template and clone_template in the sibling set. It does not explicitly name those siblings, so it stops short of full differentiation.

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 line 'Starting from one is almost always better than writing a script from nothing' nudges toward using templates, but gives no guidance on when to call list_templates versus get_template or clone_template, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the agent knows this is a safe, non-mutating, closed-world read. The description adds no extra behavioral context like pagination, authentication requirements, or response 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?

A single efficient sentence with no waste. Very concise, though might be slightly under-specified for an agent needing more context.

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

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

Given no parameters, rich annotations, and no output schema, the description is minimally adequate. It states what is listed but doesn't clarify the return format or how themes relate to projects (e.g., are they global or per-project?).

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?

Zero parameters, so baseline is 4. The description does not need to compensate for schema details since there are none to document.

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 verb 'list' and resource 'themes', but 'visual themes a project can use' is somewhat vague and doesn't clearly distinguish it from siblings like list_templates or list_sources. Could be mistaken for a templating or layout tool without more context.

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

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

No explicit when/when-not guidance or mention of alternatives. It's implied to be used when you need to discover available themes, but there is no routing to other list_* tools or exclusions.

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

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

Annotations indicate read-only, idempotent, and not open-world, so the description doesn't need to cover safety. The description adds context about the diagnostic use case, which is helpful, but doesn't disclose pagination behavior, return format, or rate limits. With annotation coverage, this is a moderate addition.

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

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

Two sentences with zero waste. The first states the purpose, the second front-loads the diagnostic value. Very efficient and 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?

Given annotations cover safety and schema covers parameters, the description provides context for use. However, it lacks details on return format, pagination behavior, or potential error states, which would be helpful for a list tool. No output schema exists, so the description could do more to explain what a delivery attempt record contains.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any meaning beyond what the schema provides about parameters like page, status, per_page, webhook_id. Baseline 3 is appropriate when 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 (List) and resource (a webhook's delivery attempts), which clearly distinguishes it from list_webhooks and get_webhook. However, it doesn't explicitly differentiate from test_webhook or trigger_analysis, which also deal with webhook activity. The purpose is clear but lacks sibling differentiation.

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

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

Provides a clear context for use: 'The place to look when a customer says events stopped arriving.' This implies when to use it, but doesn't specify when NOT to use it or alternate tools like test_webhook. No explicit alternatives mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and repeatability are covered structurally. The description adds only the scoping fact that results are limited to the current community, with no word on pagination, ordering, or result size.

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

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

A single front-loaded sentence with zero filler, which is the right shape for a no-argument list tool. It is arguably too terse to be maximally useful, but there is no wasted text.

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-param read tool with annotations carrying the safety profile and no output schema, the essentials are present. However, an agent is left guessing about result volume, pagination, and whether archived or inactive webhooks are included, which matters for a listing 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?

The tool takes zero parameters, so the baseline is 4. The description cannot and need not document parameter syntax, and nothing in it misrepresents the empty schema.

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

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

States a specific verb (List) and resource (webhook endpoints) and scopes it to 'this community's', so the agent knows exactly what is returned. It does not explicitly differentiate itself from adjacent siblings like list_webhook_deliveries or get_webhook, but the verb+resource pairing 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?

Usage is only implied: an agent can infer this is the enumeration tool for webhooks. There is no statement of when to prefer it over get_webhook (single fetch) or list_webhook_deliveries (delivery history), and no exclusions or prerequisites 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?

Annotations only declare the generic profile (readOnly=false, idempotent=false, destructive=false); the description adds real side-effect context the agent could not infer, namely that members see the result on their profile and that role-linked accomplishments grant or remove a Discord role. Minor tension with destructiveHint=false given role removal, but the action is reversible so it is not 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?

Three tight sentences that front-load the action and then layer consequence and id sourcing. The unexplained 'Outward:' prefix is minor noise that does not fit the surrounding style.

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

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

For a 3-required-parameter mutation with no output schema, the description covers side effects and id provenance but leaves the operation vocabulary and its expected values undefined, which an agent needs in order to invoke it correctly.

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

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

Schema coverage is only 33% (member_id is documented), and the description adds a useful source hint for achievement_id. However, the required 'operation' parameter has no description and no enum, and the description never states the valid values (award/revoke) even though it references both concepts.

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

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

Names a specific verb pair (award or revoke) and the exact resource (one of a member's accomplishments), and its effect on profile and Discord roles makes it clearly distinct from sibling modify_xp.

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 sourcing guidance for the id parameter ('Accomplishment ids come from get_community with expand=achievements'), which tells the agent the prerequisite call. It stops short of explicitly contrasting with modify_xp or stating when awarding vs revoking is appropriate.

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

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

Adds substantial side-effect detail beyond the annotations: the change is member-visible, moves them on the leaderboard, and can cross a threshold that grants a Discord role. It also clarifies arithmetic behavior (subtract floors at 0, set is absolute) that would otherwise be guessed. It does not say whether losing XP revokes a previously granted role, nor whether any permission is required — a meaningful gap for a non-idempotent mutation.

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 and front-loaded: the outward effect leads, followed by side effects and semantics, with no filler sentences. The unexplained 'Outward:' label is slightly awkward but functional.

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

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

With no output schema and a non-idempotent mutation, the description supplies the important consumer-facing consequences, arithmetic rules, and a confirmation guardrail. Missing only permission requirements, anything about returned data, and role-revocation behavior on XP loss.

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

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

Schema coverage is only 33% and `operation` has no enum, so the description has to carry the meaning — and it does, naming add/subtract/set and distinguishing absolute `set` from delta semantics. `amount` bounds and signedness remain unspecified, and `member_id` is left to the schema.

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

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

Opens with a precise verb set and resource: 'Add, subtract or set a member's XP.' The operation enumerations plus the XP resource make it easy to separate from siblings such as modify_accomplishments or get_xp_history, which operate on different data.

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

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

Gives a concrete call-time precondition ('Confirm the number with the human before calling'), which is real usage guidance. It does not, however, state when to prefer this tool over alternatives or when it should not be used at all, so it stops short of a 5.

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

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

Annotations only say it is not read-only and not idempotent; the description adds the irreversible side effect (invitations reach real members and cannot be taken back), the 409 script_validation failure mode, that unaccepted warnings block the call unless fingerprints are passed in acknowledge, and the MissingPostChannel warning for private projects. This is far beyond what annotations convey.

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

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

Front-loaded with the core action before the conditional detail, and nearly every sentence carries operational weight. It is still a dense, long single block; a few clauses could be tightened or split for 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?

For a 3-parameter mutation with no output schema and no annotation depth, this covers the branches an agent needs: when posting occurs, when it can be skipped, how to surface data.share_url, how validation errors and warnings are resolved, and the deferral path.

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

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

Schema coverage is only 33% (project_id documented; acknowledge and delivery are not), so the description must compensate. It does explain acknowledge (human-supplied fingerprints) and the key nested field delivery.invitation.post_channel_id (null for web-only opens), but leaves other nested fields such as audience.participation, closing, and answer_surfaces unaddressed.

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

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

States a specific verb and resource ('Activate a project and deliver it to members') and clearly separates itself from siblings by naming update_project with a scheduled delivery.opening for the deferred case and validate_script for pre-flight preview. An agent can pick this tool correctly without inspecting 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?

Explicit when-to-use rules: always opens immediately, must confirm with the human first because posts/DMs are irreversible, run validate_script beforehand, and use update_project instead when opening later. It also branches usage by participation mode (open_web/private vs Discord).

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 it is not read-only, not destructive, not idempotent, but the description adds the crucial unannotated fact that each call burns community credits and describes the returned payload. It does not explain why a planning call is non-read-only, leaving a minor gap between the observed behavior and the readOnlyHint=false 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?

Four dense sentences, front-loaded with the core purpose and cost, then the return shape, then routing, then the parameter hint. Every sentence carries distinct information with no filler.

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

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

With no output schema the description compensates by describing the return payload, and it covers cost and downstream handoff. The main shortfall is a documented 'intent' parameter and the 'language' field, but an agent can call this correctly overall.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It explains admin_language well ('the person's language so the plan and author_notes are written in it') and hints at question_count via 'up to 3 questions', but leaves intent and the language parameter undocumented, so half the parameters remain uninterpretable.

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 action ('Ask the AI what it would draft and what it needs to know') and enumerates exactly what comes back (outline, up to 3 questions with suggested answers, facts). It is clearly distinguished from the generate_script sibling, which it names as the downstream step.

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?

Explicit when/when-not ('Optional', 'Skip it when the request is already complete'), cost guidance ('spends a few hundred of the community's credits'), and a concrete workflow routing ('pass plan, answers and session_id to generate_script or create_project'). This is unusually complete routing for an agent.

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 description explicitly warns that omitted blocks are deleted and block ids change, i.e. it performs destructive updates to existing script data. The annotations declare destructiveHint=false (and idempotentHint=false), which claims only additive behavior. The text and the structured annotation tell the agent opposite things about whether existing data is destroyed.

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

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

Four sentences, each load-bearing: action, destructive semantics, precondition + alternative, and authoring prerequisite. Front-loaded with the core purpose and no filler.

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

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

For a complex mutation tool with no output schema, the description covers preconditions (project inactive), side effects (deletions, id renumbering), the alternative tool, and where to learn the non-guessable block vocabulary. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema description coverage is 50%: project_id is documented in the schema, blocks is not. The description compensates by flagging that block type names, section names, and piping rules 'are not guessable' and pointing to an external authoring resource, but it does not itself add per-field meaning for the large nested BlockSchema. Baseline 3 for mid coverage.

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

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

States a specific verb and resource ('Replace every block of a project's script') and immediately clarifies scope ('Whole-script replace'), which cleanly separates it from the sibling update_block. An agent can distinguish intent from add_block/update_block without opening any schema.

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

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

Explicit when-to-use routing: 'To change one block on a live script, use update_block,' plus a hard precondition ('The project must be inactive') and a required prerequisite read ('Read the subo://guide/authoring resource'). Names alternatives, exclusions, and preconditions all at once.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: it discloses that the old secret stops verifying immediately, that deliveries will be rejected until a human deploys the new secret, and that the new secret is returned exactly once. This is exactly the operational context an agent needs before calling a destructive rotation.

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

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

Three tight sentences, front-loaded with the 'Destructive:' marker so the risk is the first thing read. Every sentence adds distinct operational information with no filler.

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

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

For a one-parameter destructive tool with no output schema, the description covers everything needed: trigger semantics, the immediate breakage window, and the one-time return of the new secret. No material gap remains.

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 webhook_id parameter is already documented in the schema as coming from list_webhooks. The description adds no parameter detail, so the schema carries the full burden; 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: issuing a new signing secret for a webhook. An agent can tell this apart from update_webhook or create_webhook without opening schemas, since the secret-rotation semantics are named explicitly.

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

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

Usage is implied by the consequence description ('the old secret stops verifying immediately'), which tells the agent this is a deliberate rotation action. However, it never states when to choose this over siblings like update_webhook or test_webhook, nor any prerequisites, so 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?

The description says it 'makes a real request to a third-party URL the community configured', which is an open-world outbound interaction, yet the annotations declare openWorldHint=false. This directly contradicts the structured safety profile, so the disclosure is misleading rather than helpful (the 'signed payload' detail is otherwise good context).

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

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

Two short sentences, front-loaded with the action and immediately followed by the side-effect disclosure. No filler.

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

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

With no output schema and one fully documented parameter, the description covers the key operational fact an agent needs (a real outbound request is made, not a dry run). It is complete enough for invocation, though the openWorld mismatch with annotations undercuts its reliability.

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

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

There is a single parameter with 100% schema description coverage ('Webhook id, from list_webhooks.'), which already tells the agent where to obtain the value. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb+resource: sending a signed test payload to a webhook endpoint. It is clearly distinguishable from the surrounding webhook CRUD siblings (create_webhook, delete_webhook, list_webhook_deliveries) because it fires a live test rather than managing configuration.

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

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

The description implies the tool's purpose (verifying a configured webhook) but never states when to use it versus alternatives such as list_webhook_deliveries or update_webhook, nor any prerequisites. Usage is inferable but not explicit.

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

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

Goes well beyond annotations by disclosing that it spends AI credits, runs asynchronously in the background, that `force` costs full price again, and that it can be refused with a named error code. Annotations only flag readOnly=false and idempotent=false; the description supplies the cost, async, and failure 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?

Front-loads purpose, then layers cost/async, force semantics, and failure mode in a tight sequence. Dense but every clause carries operational 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?

With no output schema, the description correctly explains where the result appears (get_analysis) rather than in the reply. It covers cost, async execution, the force flag, and the refusal path, leaving nothing needed to invoke it correctly.

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

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

Schema coverage is 50%: project_id is documented in the schema, but `force` only has a title and default. The description compensates by explaining what `force` does ('re-summarizes blocks that already have a summary, at full cost'), adding meaning the schema omits.

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 ('Summarize open-text answers with AI') and clearly distinguishes the trigger action from its sibling get_analysis, which reads the result. An agent can tell this is the action that initiates analysis versus the one that fetches 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?

Explicitly routes the agent: 'read the result with get_analysis, do not expect it in this reply.' Names the alternative tool and the condition for each. Also states the refusal condition (text_analysis_off) and how to diagnose it via get_analysis.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower. The description goes beyond them with two genuinely useful behavioral facts: writes are partial ('Only the fields you pass change') and renaming does NOT cascade to `[Name]` references. Auth requirements and error behavior remain undisclosed, keeping it at a 4 rather than 5.

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

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

Three tight sentences, front-loaded with the core action, then the partial-update rule, then the caveat. No filler; every sentence carries information an agent needs before calling.

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 30-parameter mutation tool with no output schema and sparse param descriptions, the description is thin — it covers the partial-update contract and the reference-rewrite gotcha but nothing about field semantics or valid combinations. The rich nested $defs (ScaleSchema, ConditionSchema) compensate somewhat, but the definition is still incomplete for this complexity.

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

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

Schema description coverage is only 7% (just block_id and project_id), so the schema does not carry the load for the 28 undocumented fields. The description adds one high-value semantic that spans all parameters — partial-update behavior — but leaves the meaning and valid values of the remaining fields unexplained.

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

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

States a specific verb and resource — 'Update one block in place' — which is unambiguous against add_block and delete_block. It does not explicitly name or differentiate itself from siblings, but the singular 'one block, in place' framing is clear enough for selection.

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 routes the agent to validate_script after edits and implies partial-update usage, but never says when to choose update_block over add_block or how it interacts with get_script. Usage is implied rather than stated.

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

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

Annotations declare non-readonly, non-idempotent, non-destructive, and the description corroborates with partial-update semantics (only passed groups touched) plus the non-obvious propagation rule for `defaults` (future projects only). It adds meaningful context beyond the hints but omits auth/permission requirements.

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

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

Three sentences, front-loaded with the core action, and each subsequent sentence adds a distinct behavioral fact with no filler. Efficient and well-ordered.

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

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

For a tool with a deeply nested, optional-only argument tree and no output schema, the description covers the highest-value subtleties (partial updates, defaults propagation) but leaves most settings groups, permissions, and the response shape unexplained. Adequate but with clear gaps.

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

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

Schema description coverage is 0% and there are 8 top-level params, several of them nested groups. The description only adds meaning for `name`, `locale`, and elaborates `defaults` (privacy mode, theme, interviewer); the general, rewards, platforms, experience, and icon_url groups are left unexplained, so compensation is well short of what's needed.

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

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

States a specific verb+resource ("Update this community's name, locale or settings groups") that cleanly separates it from siblings like update_project, update_block, and update_webhook. It enumerates the updateable surface at a high level, though it does not name a sibling alternative to route against.

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?

"Only the groups you pass are touched" is real partial-update usage guidance, and the note that `defaults` affects future projects rather than existing ones tells the caller when the change takes effect. It lacks explicit when-not-to-use or alternative-tool routing, keeping it short of a 5.

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

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

Goes well beyond the annotations by disclosing partial-update semantics ('Only the fields you pass change'), atomic whole-script replacement and its inactive-project precondition, and the self-opening/self-closing schedule behavior with a human-confirmation requirement. These are exactly the non-obvious traits the annotations (readOnly/destructive/idempotent hints) 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 core purpose, then progresses to field-level and scheduling caveats. The scheduling paragraph is long but every clause carries actionable information; there is little 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 10-parameter tool with 10% schema coverage and no output schema, the description covers the highest-risk behaviors (partial updates, script replacement, scheduled open/close and the human-confirmation norm). It is close to sufficient, though several top-level parameters remain undocumented in both schema and prose.

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

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

Schema description coverage is only 10% (essentially just project_id), so the description must carry the load. It adds meaning for `script` (atomic replace) and `delivery.opening`/`delivery.closing` (the `{mode, time}` shape), but leaves `presentation`, `privacy_mode`, `scoring_enabled`, and `max_completes_per_user` entirely unexplained, so compensation is partial.

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 ('Update a project's name, privacy, rewards or settings') and enumerates the updatable domains. It does not, however, distinguish itself from the sibling replace_script even though passing `script` also replaces a whole script, so the boundary with that sibling is left ambiguous.

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

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

Gives a real precondition ('requires an inactive project') and an explicit when-not instruction ('do NOT call open_project') for scheduled opening, which is genuine routing guidance. It still omits when to prefer replace_script over passing `script` here, so the alternative-space is only partly covered.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still earns credit by disclosing the non-obvious replacement semantics of `events` ('replaces the whole list rather than adding to it'), a behavioral trait not derivable from the schema. It does not state whether omitted fields are left unchanged, which is the one remaining gap.

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

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

Two sentences with zero waste; the core purpose is front-loaded and the important caveat follows immediately. Every sentence earns its place.

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

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

For a mutation tool with no output schema, the description covers the main fields and the tricky events behavior, but omits the critical update semantic of what happens to fields that are not passed (all params are nullable with null defaults). An agent cannot tell from the definition whether omitting a field preserves or clears it.

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

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

Schema description coverage is only 20% (only webhook_id is documented), so the description must compensate. It names three of the four optional fields (url, events, is_active) and clarifies the replace semantics of events, but ignores `name` and gives no indication of what null/default values do for omitted fields.

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 ('Update') and resource ('a webhook') and enumerates the mutable fields (URL, events, active state). It is clearly distinguishable from create_webhook, delete_webhook, and get_webhook, though it does not name any sibling explicitly and omits the 'name' field from the list.

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

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

There is no guidance on when to use this tool versus alternatives such as create_webhook or the block/project update tools. Usage is only implied by the verb, and no prerequisites (e.g. needing a webhook_id from list_webhooks) are stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered, but the description adds genuinely new behavior: validation never persists changes, errors block open_project while warnings do not, and warnings are advisory. It stops short of describing the shape of the returned errors/warnings, though no output schema exists to cover that.

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

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

Four short sentences, front-loaded with the core action and each subsequent sentence adding a distinct, load-bearing fact (draft vs stored, error/warning consequence, call timing). No filler.

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

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

For a two-parameter read-only validator with no output schema, the description covers the essential decision points (when to pass blocks, what errors mean downstream). The only gap is that it does not hint at the returned structure, which the absence of an output schema would otherwise justify explaining.

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

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

Schema description coverage is only 50% (project_id documented, blocks undocumented), so the description must compensate. It does explain the meaning of `blocks` (a draft not yet saved) versus omitting it, which is the decisive semantic an agent needs, though it does not describe the block object contents.

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 ('Check a script for errors and warnings') plus the key scoping fact that it does not save. This clearly separates it from get_script, replace_script, and plan_script without needing their schemas.

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

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

Gives explicit conditional guidance: pass `blocks` for an unsaved draft, omit it to validate the stored script. It also states a concrete trigger ('Call this before every open_project'), so the agent knows both when and how to invoke it.

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