FindAgent

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

It discloses important behavioral constraints beyond the annotations: the token binds to the authenticated email, and tokens sent to other emails, expired tokens, or reused tokens are rejected. The readOnlyHint=false annotation is consistent with this mutating action.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the critical constraint about email binding and token validity follows immediately.

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 tool with an output schema, the description covers what the tool does, where the token comes from, and the key failure conditions. Nothing essential is missing for an agent 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?

The schema already documents token with 100% coverage, but the description adds meaning by specifying it is the raw token from an invite link and by explaining validity constraints such as email binding and expiry/reuse rejection.

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: 'Accept an organization invite' using the invite token. It also adds a key scoping detail—binding to the authenticated FindAgent email—which distinguishes it clearly from sibling tools like invite_member or leave_org.

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 makes the intended use clear: call this when you have a token from an organization invite link. It does not explicitly name alternatives or exclusions, but the action is unique enough among siblings that the context is sufficient.

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, and the description explains why that is truthful: it 'returns config only — the actual install happens when you complete the sign-in in your client.' It goes well beyond the annotations by enumerating the three distinct result statuses (purchase_required, needs_input, external_mcp_server), the hosted URL format, and the fact that FindAgent is not in the loop for external listings.

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: capability first, then return payload, then failure modes, then the external-server caveat. Every sentence carries information, though the four-sentence run-on covering entitlement and error states could be tightened slightly for scanning.

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?

Despite an output schema existing, the description still characterizes the returned config (hosted URL, mcp.json block, Claude Code command, sign-in steps) and all non-success statuses. Combined with readOnlyHint and openWorldHint annotations, an agent has everything needed to call this and interpret the result.

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

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

Schema coverage is 100% for the single slug parameter, so the baseline is 3, but the description adds real meaning: the slug must be a *published* agent slug, where to obtain it (findagent_browse_agents), and what each class of invalid slug produces. It stops short of any format/syntax guidance beyond that.

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

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

States a specific verb and resource ('Add a published FindAgent agent ... as a hosted MCP connector') and immediately scopes it by entitlement. It also names the sibling tools it is not (findagent_browse_agents for discovery, findagent_buy_agent for purchase), so an agent can route correctly without opening another 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 and when-not-to-use: free agents always work, unowned paid agents return purchase_required pointing at findagent_buy_agent, unknown/unpublished slugs return needs_input pointing at findagent_browse_agents, and MCP server listings take a different path entirely. The alternative tool for each blocked case is 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 only say readOnlyHint=false and openWorldHint=false. The description goes well beyond them: asynchronous ingest pipeline (parse → structure-aware chunk → embed with the KB's bound key), hash-based de-duplication where re-adding is a no-op surfaced via the `deduped` flag, and the embedding-key precondition. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with purpose and the primary disambiguation, and nearly every sentence carries a distinct fact (alternative tool, file path, async pipeline, dedup, prerequisite). Slight redundancy between the opening clause and 'Add a text document…' keeps it just short of 5.

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

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

For a write tool with an output schema already present, the description fills in what the structured fields do not: the async ingest model, dedup semantics and its response flag, the embedding-key precondition, and the file-vs-text boundary. Nothing needed to call it 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 100%, so the schema already documents text (plain text, max 1 MB), kb_id (from findagent_list_kbs), and the optional title default. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Puts CONTENT INTO a knowledge base' / 'Add a text document'), and explicitly names the sibling it is not — findagent_attach_kb — plus the file-upload path. An agent can distinguish this from attach_kb and the uploader 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?

Explicitly covers when-not-to-use (findagent_attach_kb for reachability; web uploader for PDF/markdown/docx) and states the hard prerequisite that the KB must have an embedding key bound or ingest fails. This is a complete routing decision.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, but the description adds substantial behavior: the authorization requirement for org targets, that org KBs are auto-available to every agent/department run for active members, what each mode actually does at runtime, and that attachments are not part of the agent manifest so updates need no re-publish. This is context an agent cannot get from 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?

Front-loads the core action and the add_kb_document contrast, then handles targets, mode, and the manifest detail in a logical order. Slightly long, but nearly every sentence carries distinct operational value rather than padding.

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

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

An output schema exists, so return values need not be described, and the definition still covers authorization, target identification, mode semantics, and a non-obvious deployment caveat. Sufficient for an agent 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 100%, so the baseline is 3, but the description adds real meaning: it explains what each mode value does operationally (tool grants a search_knowledge tool, auto_inject prepends passages), recommends target_slug over target_id, and clarifies omission of target fields for user_personal. This goes beyond the terse enum labels.

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 (connects/attaches) and resource (an EXISTING knowledge base) and explicitly scopes it against the sibling findagent_add_kb_document, which handles content addition. An agent can differentiate this from add_kb_document without opening either schema.

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

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

Gives concrete when-to-use conditions: attach a KB you own to an agent/department you own, to an org you administer, or as a personal KB. Names the exact lookup tools for each target type (findagent_list_my_agents, findagent_list_orgs) and states the auth requirement (org owner/admin). Nothing is left 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 only supply readOnlyHint=false and openWorldHint=false; the description goes well beyond, disclosing the re-queue side effect, the deliberate no-secret-in-arguments design, the no-op-and-report behavior when no key is stored, and the owner-only permission requirement. These are exactly the traits an agent needs before invoking a 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?

Front-loads the action and its effect, then layers constraints in descending priority. The secret-handling point is restated across two sentences ('NO API KEY IS PASSED HERE' / 'a secret never travels through a tool argument'), which is mild redundancy, but every other sentence carries real information.

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

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

With an output schema present, return values need not be described, and the description covers the remaining gaps: prerequisite state, side effect, failure/no-op behavior, and permissions. Nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100% and the single kb_id parameter is fully documented in the schema, so the baseline is 3. The description confirms provenance (from findagent_list_kbs) but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource — pointing an existing KB at the already-stored embedding key — plus a second concrete effect (re-queuing documents that failed on a missing key). This is clearly distinguishable from siblings like create_knowledge_base or add_kb_document, which create or populate rather than re-point.

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 triggers ('when findagent_list_kbs shows embedding_key_bound:false', 'documents are stuck failed on a missing key') and names the sibling that reports the needed signal. It also states what this tool is NOT for — adding a key, which is a web action — routing the agent away from a wrong invocation.

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, so safety is covered. The description adds behavioral context: it is paginated, explains the offset/next_offset mechanism and has_more flag, and lists the exact return fields. It does not contradict annotations and discloses all relevant operational behavior without being redundant.

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 compact but information-dense, leading with the core purpose and then layering details. It is structured logically (scope, returns, filters, pagination, alternative) and avoids fluff, though it is slightly longer than the minimum needed.

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

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

An output schema exists, so return values are already defined. The description covers pagination, filters, and the relationship to sibling tools, leaving no missing operational guidance for a read-only listing tool. It is complete for an agent to call it correctly.

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

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

Schema coverage is 100% and each parameter already has a detailed description (e.g., offset explains pagination, category_slug references findagent_list_categories). The description repeats these details without adding new meaning, so it provides marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific action: browse the PUBLISHED catalogue with pricing, and clearly enumerates the returned fields and filters. It also distinguishes itself from sibling tools by referencing the website listing and explicitly naming findagent_get_agent for single-agent detail, making its scope unambiguous.

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

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

It gives a clear alternative: 'Use findagent_get_agent for the full store view of one slug,' which tells the agent when to prefer another tool. It also references findagent_list_categories for category slugs, but does not enumerate other exclusions (e.g., when to use findagent_list_my_agents). This is clear context with a single explicit alternative, but not exhaustive 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 description adds significant behavioral context beyond the sparse annotations: the new version 'goes to admin review', the live version 'keeps serving until it is approved (never auto-unpublished)', capability changes 're-run the same security scan + auth_ref↔host check', and a price change 'applies immediately (not retroactive)'. It also warns that passing `tools` 'REPLACES the agent's whole tool surface'.

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

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

The description is dense and front-loaded with the primary action, and every sentence carries operational constraints (review flow, price immediacy, owner-only, code-bundle exclusion). It is long and run-on, but the information density justifies the length.

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

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

For an 11-parameter mutation tool with nested objects, the description covers the approval lifecycle, security re-scan, auth binding requirements, tool-surface replacement semantics, pricing behavior, and owner authorization. Combined with the high schema coverage and output schema, an agent has everything 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?

With 91% schema coverage the schema already documents most parameters, and the description still adds meaning: `bump` is a semver patch/minor/major, `tools` means a full replacement rather than a delta, `changelog` is auto-drafted when tools change, and `credential_slots` are 'DEFINITIONS ONLY — never send secret VALUES'. This substantially helps an agent construct a correct call.

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

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

The description opens with a specific verb and resource — 'Publish a NEW version of YOUR OWN published doer/declarative agent for review' — and immediately identifies the actor ('YOUR OWN', 'Owner-only') and the semver bump. It also distinguishes itself from siblings by explicitly excluding code-bundle agents ('re-version through the code wizard, not here').

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

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

It states clear context for use: publishing a new version, editing prompt/tools, and triggering re-review, and it gives one explicit exclusion (code-bundle agents use the code wizard). It does not enumerate alternative tools such as findagent_edit_price or findagent_rollback_version, so the when-not guidance is partial rather than exhaustive.

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

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

The description goes well beyond the annotations, disclosing that payment is handled by Paddle in the browser, warning never to share card details, and enumerating possible return states such as already_free, already_owned, checkout_not_live, and needs_input. It also notes the authentication requirement (signed in to FindAgent), which is useful behavior 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?

Although the description is a single dense paragraph, every sentence contributes distinct information: the main purpose, return statuses, browser/payment behavior, security warning, follow-up action, and error case. The first sentence is front-loaded with the core action, and nothing is redundant 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?

Given the tool's complexity, one required parameter, an output schema, and a large sibling set, the description is complete. It covers when to use it, what it returns, how payment works, security constraints, next steps after purchase, and fallback behavior for invalid slugs, so an agent has everything 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?

The input schema already fully documents the slug parameter with 100% coverage, so the baseline is 3. The description adds extra meaning by specifying that an unknown or unpublished slug yields a needs_input result, and clarifies the slug should come from findagent_browse_agents, which enriches the schema's plain type description.

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

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

The description states a specific verb and resource: it gets a browser checkout link to purchase a paid FindAgent agent. It clearly distinguishes itself from related tools like findagent_add_connector and findagent_browse_agents by naming exactly what it returns and when it applies.

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

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

Usage is explicitly conditional: free agents route to findagent_add_connector, already-owned agents return already_owned, and unknown slugs point back to findagent_browse_agents. It also states what to do after purchase settles, leaving no ambiguity about when this tool should be invoked.

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?

readOnlyHint=false already indicates mutation, and the description adds meaningful behavioral detail: ownership changes require an owner, admins can only toggle admin↔member, and the last owner is protected. This goes beyond the annotations and helps the agent anticipate access restrictions.

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 no filler. The primary action is front-loaded, followed by the most important permission rules and a key business constraint. 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?

The description covers the main operation, permission rules, and a critical invariant. An output schema exists so return values need not be described. One minor gap is that org_id/slug are optional in the schema and the description does not explicitly say one of them is required, but overall the tool is adequately 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 100%, so the baseline is 3. The description adds value beyond the schema by explaining role constraints and who can set which role, which directly informs how to fill the 'role' parameter. It could be more explicit about needing one of org_id/slug, but the constraint semantics are valuable.

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 ('Change') and resource ('a member's role in an organization'), and immediately distinguishes the operation from related tools like invite/remove/transfer by stating the permission model. The scope is clear even 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?

The description gives clear context for when to use the tool: to change roles, with explicit permission constraints (owner vs admin) and an edge case (last owner cannot be demoted). It does not explicitly name alternative sibling tools or say when not to use it, but the usage context is strong.

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

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

Annotations already state readOnlyHint=true, but the description goes far beyond that by specifying the exact return shape ({ valid, available }), the meanings of each value (valid=false for malformed, available=false for taken, available=null for inconclusive), and the note that create_draft still enforces uniqueness even when inconclusive. This discloses edge-case behavior that annotations cannot convey. There is no contradiction with annotations.

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

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

The description is information-dense but well-structured: it leads with the core action and purpose, then explains the return contract, then the validation rules, then the preferred alternative. Every sentence earns its place; there is zero filler or repetition. The critical guidance is front-loaded, and the alternative is stated at the end without weakening the primary message.

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

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

For a single-parameter, read-only validation tool with a fully documented schema and an output schema, the description is complete. It covers the tool's purpose, the expected return values and their edge cases, and explicitly routes the user to the preferred alternative. There is nothing an agent needs to know to call this correctly that 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?

The schema describes slug as a string with format 'kebab-case, 3–60', but the description expands on this with concrete validation rules: 'no leading/trailing hyphen' and explains how the slug's validity maps to the return values. This adds practical meaning beyond the schema's type constraints, showing the agent exactly what constitutes a valid input.

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 ('Check'), a clear resource ('agent slug'), and the exact criteria ('well-formed AND available'). It explicitly distinguishes itself from siblings by stating it runs 'before findagent_create_draft' and naming the recommended alternative findagent_submission_wizard. An agent can immediately understand the tool's function without any ambiguity.

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 provides explicit usage context: 'before findagent_create_draft' sets the timing, and 'Prefer findagent_submission_wizard' directly names the alternative and indicates it should be chosen over this tool in normal flows. This is a clear when-to-use and when-not-to-use directive, with a specific 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?

Goes well beyond the readOnlyHint annotation by explaining that the tool itself grants nothing, the actual connect happens in the browser, and the token is stored server-side. It also discloses account scoping, which is non-obvious behavioral context not visible in the schema or annotations.

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

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

Every sentence earns its place: purpose, expected return, browser-based authorization flow, when to call, account scoping, and the disconnect alternative. Information is front-loaded and each clause adds distinct value.

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

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

For a zero-parameter tool with an output schema, the description fully covers the calling context, the browser flow, server-side token storage, account scoping, and prerequisite ordering. Nothing an agent needs to invoke this correctly is missing.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description correctly focuses on behavior and usage rather than inventing parameter detail.

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

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

States a specific verb and resource ('Start connecting GitHub') and explicitly frames it as a prerequisite for findagent_import_repo / findagent_list_repos, which distinguishes it from those sibling tools. The mention of disconnecting also separates it from findagent_disconnect_github.

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-to-use guidance: 'Call this first if import_repo or list_repos reports github not connected.' It also addresses a common alternative need by directing users to findagent_disconnect_github first when switching GitHub accounts.

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 readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden; it discloses server-side re-pull with the stored GitHub token, snapshot/scan/validation, status=draft ownership, idempotent overwrite with an 'updated' flag, and the admin-approval gate. It also clarifies that credential_slots only declare shape and never carry secret values, which is critical safety context. No contradictions with 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?

Six dense sentences, each delivering a distinct fact: purpose/condition, payload composition, execution behavior, idempotency, secret policy, and gating. The description is front-loaded and free of filler; heavy use of caps and parentheses packs information efficiently. Given the tool's 21-parameter complexity and nested objects, the length is justified.

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 21 parameters, nested objects, and an output schema, no description can enumerate everything, but this one supplies the missing workflow glue: where input values come from, how to override them, the required next call, and the overwrite semantics. It even notes the 'updated' response flag. Nothing essential for correct invocation is absent.

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

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

Schema description coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds a valuable grouping (basics vs. the detected contract from import_repo's grounding.code_bundle) and the notion of overriding detected values, plus the 'example_prompts required' rule. This is meaningful but largely reinforces and organizes what the schema already states, so it does not reach 5.

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

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

The description opens with 'Persist a CODE-BUNDLE draft from YOUR OWN GitHub repo', a specific verb plus resource, and immediately ties it to the condition 'use this when findagent_import_repo returned grounding.code_bundle'. This clearly distinguishes it from the sibling findagent_create_draft and any generic draft tool. No interpretation is left to the agent.

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

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

It explicitly states when to use the tool (after import_repo returns grounding.code_bundle) and what to do next ('then call findagent_submit_for_review IN THIS MCP CLIENT'), including the idempotency-driven iteration workflow. It also gives safety guidance on when NOT to send secret values. The alternative for non-code-bundle drafts is implied rather than named, but the precondition is an unambiguous discriminator.

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=false, consistent with 'Creates a status=draft agent' — no contradiction. The description adds non-obvious behavioral context beyond annotations: the draft is incomplete until submitted in this client, the web is not the finish point, credential_slots declare SHAPE only (never secret VALUES), and kind is inferred from whether `tools` is passed. This is rich, decision-relevant 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?

A single dense paragraph, front-loaded with the core purpose before the workflow and security guidance. Every sentence earns its place and the structure (purpose → workflow → prerequisites → security warning) is logical. Slightly long, but the tool's 21-parameter complexity justifies the density.

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 the high complexity (21 params, nested objects) plus full schema coverage and an output schema (so return values needn't be explained), the description is complete. It covers the non-obvious workflow, prerequisites, security constraints on credentials, and routes to the right sibling tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the schema descriptions are already thorough. The description adds workflow linkage beyond the schema: verify slug with check_slug, pick top-level category + discipline via list_categories, and the credential shape-only rule plus kind inference from `tools`. This is genuine added value over the schema alone, earning a 4.

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

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

Opens with a specific verb+resource ('Persist a DRAFT marketplace listing') and clarifies the outcome ('Creates a status=draft agent owned by you'). It also disambiguates from siblings by naming findagent_submit_for_review, findagent_submission_wizard, and findagent_check_slug, so an agent can tell this apart from related draft/submission tools.

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

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

Gives an explicit workflow: finish via findagent_submit_for_review IN THIS MCP CLIENT, prefer findagent_submission_wizard to collect fields step-by-step first, and run findagent_check_slug + findagent_list_categories before calling. It also states the web is only an optional preview, not where the agent finishes — clear when-to-use and routing with named 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 only declare readOnlyHint=false, so the description carries the behavioral disclosure burden. It does well by warning that 'without a key, documents will not ingest' and noting the cost implication ('$0 to the platform — you use your own key'). This is valuable beyond the schema, although it does not cover all side effects (e.g., reversibility).

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 compact three-sentence block with no filler. It front-loads the core purpose, then addresses model choice and the critical key-binding caveat, and ends with optional scoping. Every sentence contributes actionable guidance.

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 that an output schema exists and all five parameters are documented in the schema, the description only needs to add the operational context. It covers the essential decisions an agent must make (model selection, key binding, org scoping) and the critical consequence of skipping the key. Nothing needed for a correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for embedding_model (small default, large for higher quality) and bind_embedding_key (necessary for ingestion), while also clarifying org_id scope. This goes beyond the schema's field descriptions without being redundant.

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 precise verb and object: 'Create a FindAgent Knowledge Base you own' and then clarifies what it is ('a document + memory store an agent can be attached to and answer grounded in, with citations'). This clearly distinguishes it from sibling operations like attach, add_document, list, or delete, so an agent can identify the correct tool.

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

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

The description provides clear context for how to use the tool: choose an embedding model based on quality, bind your OpenAI key for ingestion, and optionally scope to an organization. It does not explicitly name alternatives or when-not-to-use, but the create operation is unique among siblings and the practical conditions are well explained.

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 is unusually transparent about side effects and sequencing: the user becomes owner, the slug is permanent, the URL can never change, nothing is created until confirm_slug is provided, and the first call only returns the exact slug and a notice. This goes well beyond the minimal readOnlyHint=false annotation and prepares the agent for the two-call creation pattern.

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 information-dense but not bloated. It front-loads the core purpose, then covers the required parameters, the follow-up invite action, and the nuanced permanent-slug confirmation flow. Each sentence earns its place, and the prominent 'SLUG IS PERMANENT' warning prevents a consequential mistake.

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

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

For a creation tool with a nontrivial confirmation workflow, the description covers everything an agent needs: what to pass, what the first call returns, what the second call must contain, the permanent-URL consequence, and the next recommended tool (invite_member). The output schema exists and the input schema is fully documented, so no critical context is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it explains that slug is derived from name when omitted and clarifies the exact role of confirm_slug in the two-step flow. While the schema already documents confirm_slug well, the description adds the derived-slug behavior and reinforces the required acknowledgement semantics.

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

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

The description states a specific verb and resource: 'Create a FindAgent organization (a B2B workspace) — you become its owner.' It distinguishes the tool's purpose from siblings like get_org, list_orgs, delete_draft, and invite_member by focusing on creation, ownership, and the subsequent invite step. The scope and intent are unambiguous.

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

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

It gives clear in-flow guidance: create the org, then invite teammates with findagent_invite_member, and explicitly instructs the caller to first call without confirm_slug and then re-call with the exact slug. It does not explicitly describe when-not-to-use alternatives such as findagent_check_slug, but the workflow is clear enough to prevent misuse.

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?

Discloses material behaviors beyond the annotations: creates a status=draft agent, stores and displays the server URL only, never executes on FindAgent, auto-detects tools via a sandbox-gated live scan, and allows overrides. This is exactly the kind of mutation/side-effect context that annotations alone do not provide.

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

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

The description is dense but appropriate for a 14-parameter tool with nested objects. It front-loads the core purpose and then flows through listing basics, endpoint/schema options, auto-detection behavior, and post-call steps; nearly every sentence adds operational value, though a bit of restructuring could reduce cognitive load.

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

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

Given the tool's complexity, the description covers the essential workflow, prerequisites, follow-up action, behavioral constraints, and parameter relationships. Since an output schema exists, return-value documentation is not required, and nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds meaningful cross-parameter guidance: example_prompts is required even though the schema lists no required fields, server_json is used instead of server_url, auth_note must never contain secrets, category_slug must be top-level, and transport defaults depend on server.json. This materially improves correct invocation beyond the schema.

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

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

The description uses a specific verb-plus-resource pattern: 'List an EXTERNAL remote MCP server you run as a marketplace LISTING,' and precisely scopes what the tool does versus what it does not do. It clearly differentiates this creation flow from siblings like findagent_create_draft by identifying the remote-server listing use case and naming the follow-up submit 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?

Explicitly tells the agent to call findagent_check_slug and findagent_list_categories before invoking, and to call findagent_submit_for_review afterward. It also defines the intended scenario — your own infrastructure, buyers connect directly — which helps an agent decide when this tool is appropriate rather than a generic draft-creation sibling.

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

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

Discloses significant behavior beyond annotations: the post is public, attributed to the connected account, moderated, initially OPEN, returns a new request id, and is free with no payment. This goes well beyond readOnlyHint=false and openWorldHint=false, and nothing contradicts 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?

Every clause earns its place: action, audience/attribution, payload constraints, moderation, initial status, return value, and cost. The main operation is front-loaded in the first phrase, and the length is appropriate for the behavioral detail it conveys.

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 create tool with an output schema, the description covers identity, audience, payload constraints, moderation, initial status, return value, and payment. Nothing essential is missing for an agent 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 100%, and both parameters are already described in the input schema. The description repeats the 5–120 character title and ≤2000 character body limits without adding new semantic meaning; 'clear title' is only marginal quality guidance.

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

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

States the specific action ('Post an agent request onto the PUBLIC FindAgent demand board') and the purpose ('I want an agent that does X'), making it distinct from siblings like findagent_list_requests, findagent_vote_request, and findagent_withdraw_request. The verb and resource are unambiguous.

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

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

Provides clear use context: use when the connected account wants to publish a demand on the public board, with title/body constraints and moderation noted. It does not explicitly name alternatives or say when not to use it, so it misses exclusionary guidance that would earn a 5.

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

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

Annotations already declare destructiveHint=true, and the description adds meaningful behavioral context beyond that: this is a soft delete, the whole listing is discarded, and the slug is freed for reuse. It also repeats and enforces the owner-only constraint. It stops short of describing recoverability or audit effects, but the provided details substantially exceed annotation-only guidance.

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 compact and front-loaded: it states the action, scopes it to the user's own drafts, explains the effect, and lists exclusions with alternatives. Every sentence earns its place, and there is no filler or repetition beyond the helpful repeated emphasis on ownership.

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 annotations and an output schema, this description covers everything an agent needs to select and invoke it correctly: what it operates on, when it applies, when it does not apply, the side effect, and the owner restriction. No important context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter detail. The description reinforces that the agent must be a draft or needs-changes and your own, but this largely mirrors the schema's parameter description rather than adding new semantic information.

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

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

The description names a specific verb (discard/delete), a specific resource (YOUR OWN draft listing), and the exact states a draft must be in (never submitted or needs-changes). It distinguishes itself from live-agent lifecycle tools by explicitly stating that published/in-review agents are not deletable here and naming rollback_version/bump_version as the relevant alternatives.

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

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

The description gives both positive conditions (draft or needs-changes) and exclusion conditions (published or in-review), making it unambiguous when to use the tool. It explicitly routes live-agent work to findagent_rollback_version / findagent_bump_version and states the owner-only restriction.

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 mark destructiveHint=true and readOnlyHint=false, but the description adds valuable context: what gets destroyed (documents, chunks, structure, attachments), that attached agents lose access, and that the operation cannot be undone. It also explains the owner/admin privilege requirement.

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

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

Three dense sentences with no redundancy. The deletion scope is front-loaded, followed by authorization, side effects on attached agents, and irreversibility. 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 single-parameter destructive operation with an output schema, the description fully covers what is deleted, who is allowed to delete, the consequence for attached agents, and the fact that it cannot be undone. No essential invocation information 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?

The only parameter, kb_id, is fully documented in the schema with 'The knowledge base id to delete (from findagent_list_kbs).' Since schema description coverage is 100%, the description needing to add no parameter detail matches the baseline of 3.

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

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

The description states a specific action and object: 'Permanently delete an ENTIRE knowledge base you own.' It clearly distinguishes itself from sibling delete_kb_document by emphasizing the entire KB, including documents, chunks, structure, and attachments.

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

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

Usage context is explicit: the user must own the KB, and deleting a shared organization KB requires org owner/admin rights. It does not explicitly name an alternative for deleting a single document, but the scope and ownership requirements make the intended use unambiguous.

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

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

Annotations already include destructiveHint=true, but the description adds valuable context: the deletion is permanent and cannot be undone, it is owner-gated, and other documents remain unaffected. These details go beyond the annotation and inform the agent about side effects and authorization requirements.

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

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

The description is two sentences with no fluff. The first sentence front-loads the action, scope, and ownership, and the second emphasizes irreversibility. Every word contributes to understanding the tool's purpose and constraints, making it highly efficient.

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 delete operation with a single parameter and an output schema present, the description covers the essential prerequisites (document_id source), ownership requirement, scope, and irreversibility. It does not explain error cases or the response format, but the output schema likely covers that. The completeness is strong but not exhaustive.

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 schema provides 100% coverage for the single parameter document_id, including the instruction to source it from findagent_list_kb_documents. The description repeats this guidance but adds no new parameter-specific meaning beyond what the schema already conveys, so the baseline of 3 applies.

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

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

The description states a specific verb ('permanently delete'), a specific resource ('one document (and its chunks) from a knowledge base you own'), and clearly distinguishes it from siblings like findagent_delete_kb which deletes the whole KB. The scope and ownership constraint are explicit, making the tool's purpose 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?

The description provides clear usage context: it requires the document_id from findagent_list_kb_documents, is owner-gated, and affects only the specified document. It implies the appropriate use case is single-document deletion. While it doesn't explicitly name an alternative for bulk deletion, the one-document framing makes the distinction clear.

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

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

Annotations already flag this as destructive and non-read-only, and the description adds valuable context: it removes exactly one binding, leaves the knowledge base and other attachments untouched, and is 'Owner-gated.' This goes beyond the annotation hints to clarify both the scope of destruction and access control.

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 no filler: the first states the action and the required parameter source, and the second tightens the scope with a clear 'only that one binding' qualifier plus the ownership gate. Every word 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 single-required-parameter tool with an output schema and full schema documentation, this description is complete. It tells the agent what resource to target, where to get the ID, what will and will not be affected, and the authorization requirement—there is no meaningful 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?

The schema already documents attachment_id with a description that names findagent_list_kb_attachments as its source; the description repeats that same provenance. With 100% schema coverage, the baseline of 3 applies because the description does not add meaning beyond what the input schema provides.

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 precise verb-resource pair: 'Detach a knowledge base from an agent, department, or your personal binding.' It further differentiates the operation by clarifying that only the specified binding is removed, not the knowledge base itself or other attachments, which distinguishes it from delete_kb and similar tools.

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 tells the agent to supply attachment_id from findagent_list_kb_attachments, providing the correct source for the required parameter. It also gives scope guidance by explicitly stating what is not affected, but it does not name alternative sibling tools or list explicit when-not conditions, so it falls 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?

Annotations already provide idempotentHint and readOnlyHint, and the description adds meaningful behavioral context: it drops the stored connection, best-effort revokes the GitHub-side grant, and returns disconnected:true even when nothing was connected. This fully explains the operation's side effects and edge case 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 tightly written sentences: the core action, the behavioral notes, and the follow-up step. No filler or redundant restatement of the title.

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

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

For a zero-parameter action with an output schema, the description covers the operation's effect, idempotency, return behavior, and next step. Nothing an agent needs to invoke it 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?

The tool takes zero parameters, so the schema has nothing to document. The description correctly requires no parameter explanation, and the baseline of 4 applies because there is no parameter burden to compensate for.

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 action ('Disconnect / switch GitHub account') and resource ('stored GitHub connection'), clearly distinguishing it from findagent_connect_github. It also explains the purpose of disconnecting so a different GitHub account can be authorized.

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 explicit sequencing: after disconnecting, call findagent_connect_github to connect the new account. It also clarifies the idempotent nature, so the agent knows it is safe to call even when nothing is connected.

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

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

Beyond the readOnlyHint annotation, the description explicitly states 'READ-ONLY: this never moves money' and adds meaningful context: payouts are KYC/owner-gated and handled outside the tool. It also clarifies currency units are minor units, which is valuable behavioral/output 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?

The description is concise: three sentences with no wasted words. It front-loads the core purpose, states the read-only nature, explains the payout exclusion, and provides the currency-unit detail. 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 zero-parameter tool with an output schema, the description is complete: it identifies exactly what data the agent will receive, the read-only safety profile, the payout exclusion, and the unit convention. There are no missing behavioral or usage details needed to call this tool 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?

The tool has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because the description correctly avoids inventing parameters and instead clarifies the meaning of the returned amounts (minor units), which is useful given the empty input schema.

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

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

The description uses a specific verb ('Read') with a clear resource ('YOUR OWN creator earnings') and enumerates the exact data returned. It further distinguishes itself from any potential payout/withdrawal tools by explicitly stating those are not available as a tool.

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

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

The description clearly states when to use it: to read the caller's own earnings, balances, and recent transactions. It also gives an explicit when-not and alternative path: withdrawals/payouts are handled through the FindAgent dashboard, not through this tool.

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 provide readOnlyHint=false and idempotentHint=true, but the description adds critical behavioral context beyond that: report_instructions is prepended to EVERY member's and the orchestrator's prompt on every run, empty strings clear fields, and saves are checked against a prompt-injection deny-list and secret scan (rejected on a hit). It also states authorization constraints and explicitly lists what it does NOT change. No contradiction with 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?

Every sentence earns its place: the main purpose, the key side effect of report_instructions, the usage pattern, exclusions, authorization constraints, and a pointer to the discovery tool. It is front-loaded with the primary action and keeps all additions relevant. No fluff or repetition.

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

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

The description is complete for a tool with a full 4-parameter schema and an output schema. It covers scope, permissions, side effects, exclusions, and related tool guidance. The only thing not explained is the return value, but the output schema presumably handles that. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the partial-update pattern ('pass... only the fields you want to change'), the clearing behavior for empty strings, and the strategic role of report_instructions as a team-wide behavioral lever. These semantics are not fully covered by the schema's parameter descriptions, though the schema is already quite detailed.

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: 'Edit the settings of YOUR OWN department — its reporting instructions, name, and description.' It enumerates the exact fields and clarifies what it does not do ('does NOT change the department's composition'), which distinguishes it from sibling tools like findagent_edit_metadata and the web builder. An agent can immediately identify this tool's unique 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?

The description gives explicit when/when-not guidance: 'Owner-only, personal departments only (an org department is edited from the org workspace)' and 'composition... edited in the department builder on the web.' It also tells the agent to call findagent_list_my_agents to discover owned departments, and describes the partial-update pattern ('pass only the fields you want to change'). No ambiguity remains about when to use this tool.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description adds crucial behavioral context: it explicitly does NOT change agent capabilities, it goes live immediately, it is owner-only, and existing buyers are unaffected. This surpasses the baseline and fully discloses the non-destructive, partial-update 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?

Despite being a bit long, every sentence serves a purpose: purpose, scope, exceptions, ownership, effect, and validation source are all packed efficiently. The critical distinction from capability toggles is front-loaded, and there is no redundant 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?

Given the tool's complexity and the existence of an output schema, the description covers all necessary context: it clarifies boundaries with other tools, ownership constraints, immediate effect, and how to obtain valid categories. It also notes that existing buyers are unaffected, which is vital for an agent deciding to invoke this mutation tool.

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

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

Schema coverage is 100% with each parameter already described (including constraints like ≤10 tags, character ranges, and aliases). The description adds minimal parameter-level detail beyond the schema, but it does reinforce the partial-update pattern and the category rules. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description explicitly states the tool edits display metadata of one's own published agent, enumerates the exact fields (title, tagline, description, example output, category, tags), and distinguishes it from capability-modifying tools by naming siblings like findagent_bump_version, findagent_repull, and findagent_reintrospect_mcp. This leaves no ambiguity about scope or intent.

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

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

It clearly specifies that metadata edits go live immediately without re-review and that other tools (bump_version, repull, reintrospect_mcp) handle capability changes with admin review. It also notes owner-only access, the finger on how to pass only changed fields, and directs to findagent_list_categories for valid slugs, providing both when-to-use and when-not-to-use 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 mark this as non-read-only and non-destructive, and the description adds materially: owner-gating, audit-log recording, non-retroactivity, and that existing buyers keep access. This goes beyond the structured fields and tells the agent exactly what side effects to expect.

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 carrying a distinct constraint (ownership, price rules, non-retroactivity, validation path), with the main action front-loaded. No filler or repetition.

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

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

For a mutation tool with an output schema and full parameter coverage, the description provides all needed context: owner prerequisite, price bounds, enum semantics, and downstream impact on existing buyers. An agent can invoke it correctly without additional assumptions.

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?

Input schema covers all three parameters with descriptions and enums, so the baseline is 3. The description reinforces the 50000-cent cap and 'ignored for free' behavior, but does not add meaning 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?

The opening sentence names a specific verb ('Change') and resource ('price of YOUR OWN agent'), and adds the qualifier 'audited price-edit', making the operation unmistakable. This naturally separates it from nearby tools like findagent_edit_metadata and findagent_buy_agent.

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

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

The description clearly scopes when the tool applies: only the agent's owner may use it, and it is the validated equivalent of the web price editor. It does not explicitly name alternative tools or say when not to use this one, so it misses the top bar but is well above vague.

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 readOnlyHint and openWorldHint; the description adds substantial context beyond them: the is_mcp_server_listing field semantics (omitted when unknown, absence must not be read as false), the fact that kind is mcp-tool for both listed and run agents, that paid agents hide tools/skills until purchase, and the needs_input fallback for bad slugs. These are exactly the behavioral traits an agent needs and could not infer.

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

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

Front-loads the core purpose in the first sentence and packs edge cases into a dense but information-dense paragraph. Nearly every clause earns its place, though the packed clauses about is_mcp_server_listing/kind make it heavier to parse than it needs to be.

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

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

With an output schema present the description needn't enumerate return fields, yet it still summarizes them and covers the tricky cases an agent must handle: undetermined listing flag, paid-content hiding, and unknown-slug behavior. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% with a single well-described slug parameter, so the schema already carries the parameter meaning. The description reinforces the slug's provenance ('from findagent_browse_agents') but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (full store view of ONE published FindAgent marketplace agent by slug), and implicitly distinguishes itself from the plural sibling findagent_browse_agents by emphasizing 'ONE'. An agent can tell exactly what it retrieves 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?

Tells the agent the tool mirrors the website's agent detail page and that an unknown/unpublished slug returns a needs_input result pointing back to findagent_browse_agents, effectively routing to that sibling for discovery. It stops short of an explicit 'use this when / not when' framing, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by noting the active-membership filtering behavior, which is not visible in annotations or schema, and by outlining the returned fields. No contradiction with 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 short sentences with no filler. The primary action, resource, and return set are front-loaded, and the sibling relationship and membership constraint follow economically.

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

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

For a one-parameter read-only tool with an output schema, the description is complete: it explains what is fetched, how it is identified, what is returned, the visibility constraint, and the relationship to the sibling listing tool. No missing information an agent needs 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 for the single slug parameter is 100%, including the note that it comes from findagent_list_orgs. The description reinforces the slug-based lookup but does not add substantial parameter meaning beyond what the schema already provides, so the baseline holds.

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: 'Get one organization you belong to by slug.' It lists the returned fields (id, name, slug, role, seat count) and differentiates itself as 'The single-org companion to findagent_list_orgs,' so an agent can distinguish it from 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?

It gives clear context: used to fetch a single organization by slug, only returns organizations where the caller is an active member, and is explicitly the single-org counterpart to findagent_list_orgs. It does not explicitly state when-not to use it (e.g., 'use list_orgs for all organizations'), but the relationship is clear enough.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: nothing is persisted or executed, the pull runs server-side with a stored GitHub token, private repos are supported, and the AI client never needs repo access. This goes beyond the annotation and clarifies side effects, auth, and privacy.

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

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

The description is dense but focused: three sentences front-load the core purpose, then add workflow, cost rationale, and privacy/read-only facts. Slightly long due to embedded pipeline details, but every clause contributes useful information.

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

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

With an output schema present, the description does not need to explain return values. It covers the input constraints, expected workflow, read-only behavior, private repo handling, and server-side token use. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful access semantics: the repo must be readable by the connected GitHub token, private repos work because the pull is server-side, and refs default appropriately. This helps the agent choose parameter values correctly.

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

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

The description states a precise verb and resource: pull the caller's own GitHub repo via their connected token and return deterministic grounding plus a field contract. It enumerates the specific outputs (basics, languages, tech domains, detected tools and hosts) and distinguishes the tool from its siblings by naming the downstream workflow (findagent_submission_wizard, findagent_create_draft).

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 explicit workflow guidance: use the grounding as the basis, then run findagent_submission_wizard and finalize with findagent_create_draft. It also explains that the agent's own model does synthesis, avoiding FindAgent LLM cost. It does not spell out when-not-to-use conditions or alternatives, but the placement in the pipeline is clear.

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

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

Annotations indicate readOnlyHint=false (mutation) and openWorldHint=false, but the description adds meaningful behavior beyond that: the return of a single-use, expiring accept_url, the requirement that the invitee sign in with the same email, and the permission level required. No contradiction with annotations, and the additional context is valuable for the agent.

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 crisp sentences that front-load the main action, include the permission constraint and return behavior, and clarify edge cases. No wasted words; every clause adds value.

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

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

Given the tool's moderate complexity, the description covers all critical aspects: what it does, who can use it, what it returns (accept_url), the email-binding requirement, and the role options. The output schema exists, so return details are handled there. Nothing an agent needs to call it 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 100%, so the schema already documents every parameter (email, role, slug, org_id) with clear explanations. The description repeats some of this (e.g., role default, ownership separate) but adds no new parameter-level information beyond what the schema provides. Baseline 3 is appropriate given the high schema 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?

The description states exactly what the tool does: invite a teammate by email with a role, and explicitly distinguishes it from ownership transfer. The scope (owner/admin only) is also clear, so an agent can easily tell it apart from related sibling tools like findagent_transfer_org_ownership or findagent_change_member_role.

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 includes a permission prerequisite (owner/admin only) and states that ownership is transferred separately and never invited, which implies using a different tool for ownership changes. However, it doesn't explicitly name the alternative tool, though the sibling list contains findagent_transfer_org_ownership. It's clear enough for an agent to infer when to use this tool vs 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 mark readOnlyHint=false, which already flags mutation. The description adds meaningful behavioral context: it removes only the caller's membership and enforces a last-owner constraint. It does not fully discuss reversibility, but for a simple leave operation with output schema present, this is solid.

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 main behavior is front-loaded, and the important exception/alternative is stated immediately after. 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 simple two-optional-parameter tool with an output schema, the description covers the key facts: scope of effect, owner exception, and routing to the transfer tool. Nothing needed to call or interpret the tool 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 both slug and org_id parameters are already described in the input schema. The tool description adds no parameter-specific guidance beyond what the schema provides, so the baseline 3 score applies.

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

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

The description states a specific verb and resource: 'Leave an organization you belong to' and clarifies it 'removes your OWN membership.' This clearly distinguishes it from member-management tools like findagent_remove_member, which affect other users' memberships.

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 indicates the tool is for your own membership and explicitly names the alternative for owners: 'The last owner cannot leave — transfer ownership first with findagent_transfer_org_ownership.' It does not explicitly say 'use remove_member for others,' but 'removes your OWN membership' implies the exclusion, so usage context is clear.

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

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

Beyond the readOnlyHint annotation, the description discloses the tree-shaped output, the category_type facet, and critical validation rules about top-level slugs, discipline requirements, and mandatory subcategory inclusion. These constraints materially affect how the agent should use the returned data and are not inferable from annotations alone.

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

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

The description is dense but not bloated; every clause contributes necessary information. It front-loads the core purpose before diving into constraints, though the long run-on sentence with uppercase emphasis could be structured more cleanly. Still, efficiency is good for the complexity it conveys.

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 read-only list tool with an output schema, the description is complete: it explains what will be returned, when to call it, and how to interpret the result for the downstream create_draft flow. There are no apparent missing details an agent would need to invoke this tool 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?

This tool has zero parameters and the schema coverage is 100%, so there is no parameter gap to fill. The description adds value by referencing downstream parameters (category_slug and additional_category_slugs) that the caller will need when drafting a listing, which is useful semantic context even though those parameters belong to another tool.

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

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

The description clearly states a specific action ('List the active FindAgent marketplace categories as a TREE') and specifies what the output includes: top-level categories, category_type values, and subcategories. It also distinguishes its role in the workflow by saying 'Call this before drafting a listing,' which separates it from listing-related siblings and drafting tools.

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

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

It explicitly states when to use the tool ('Call this before drafting a listing') and names a preferred alternative for a different flow ('Prefer findagent_submission_wizard to walk the user through category selection step-by-step'). This gives the agent clear context for choosing between this tool and a sibling.

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

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

Annotations already establish readOnlyHint=true, but the description adds substantial non-obvious behavior: the auth requirement, that expired invites are included and still block new invites, and that no accept links are returned because only token hashes are stored. This is exactly the kind of security/side-effect context annotations don't carry.

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

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

A single dense paragraph with zero filler, and the most decision-relevant facts (permission scope, expired-invite inclusion) are front-loaded. It is packed but no sentence 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 an output schema present, return format needn't be re-explained, and the description fully covers permissions, the expired-invite edge case, and the token-security caveat. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%; both slug and org_id are fully documented there, including that they are alternatives and that org_id comes from findagent_list_orgs. The description adds no parameter detail, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (lists an organization's outstanding invites) and immediately scopes it to owner/admin, which distinguishes it from the member-readable list siblings like findagent_list_members. An agent can tell what it returns and who may call it 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?

Provides clear permission context (owner/admin only) and the key usage fact that this is the only way to see and clear an expired invite. It stops short of explicitly naming the alternative actions (findagent_resend_invite, findagent_revoke_invite) an agent might reach for, so it's clear context without explicit routing.

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

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

The description confirms the read-only behavior already present in annotations and adds meaningful context: the KB must be owned, the result includes attachment ids and modes, and the identifier is intended for detaching a binding. This goes beyond the annotation flags without contradicting them.

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 carry the entire message: the first states the operation and output shape, the second links the output to the relevant sibling. There is no filler or repetition of schema fields.

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

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

With a single parameter, a clear output schema, and read-only annotations, this description covers everything an agent needs to select and call the tool correctly. It also provides the cross-reference to detach, which completes the workflow context.

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 only parameter, kb_id, is fully documented in the schema with 100% coverage and its source (findagent_list_kbs). The description adds the ownership requirement ('a knowledge base you own') and clarifies what the returned attachment ids are for, giving the parameter practical context beyond the raw type.

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

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

The description opens with a specific verb ('List') and a precise resource ('where a knowledge base you own is attached'), then names the three attachment targets (agent / department / personal) and what each row contains (attachment id, mode). This differentiates it from sibling tools like findagent_attach_kb and findagent_detach_kb 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?

It states the tool's scope ('knowledge base you own') and explicitly ties the returned attachment id to findagent_detach_kb, giving a concrete follow-up use. It does not spell out exclusion criteria versus all siblings, but the purpose is clear enough that an agent can infer when it applies.

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

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

Annotations already mark readOnlyHint true; the description reinforces that with READ-ONLY and adds meaningful context about ingest lifecycle ('parsing'/'embedding' in flight, 'ready' searchable, 'failed' with error) and the ownership constraint. No contradiction with 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: purpose and statuses are front-loaded, downstream usage is one actionable clause, and the read-only flag is a deliberate final signal. Every sentence earns its place without 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?

With a single well-documented parameter, an output schema present, and safe read annotations, the description covers the full operational contract: what is listed, what the statuses mean, how it relates to aggregate listing, and how returned ids are used downstream. Nothing essential for correct invocation is missing.

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

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

The only parameter, kb_id, is already fully documented in the schema as coming from findagent_list_kbs, so the description adds no new format or syntax detail. The 'you own' qualifier is a mild additional constraint but does not materially expand parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource ('List the documents in a knowledge base you own'), enumerates return fields and exact ingest statuses, and distinguishes itself from findagent_list_kbs and findagent_delete_kb_document. An agent can immediately tell this is the per-document listing 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?

It clearly frames this tool as the per-document detail behind findagent_list_kbs's aggregate document_count and instructs using the returned id with findagent_delete_kb_document. It does not explicitly enumerate when not to use it, but the sibling relationships and read-only scoping provide enough 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?

readOnlyHint=true already communicates the safety profile, and the description reinforces it with 'READ-ONLY.' It adds useful context about visibility (own KBs plus organization KBs) and the data returned, but it does not disclose behaviors such as pagination, auth requirements, or response size limits. This matches the level of a simple list tool whose annotations already cover side effects.

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 states the action, scope, and returned fields with no filler. The 'READ-ONLY' flag is appended as a clear safety signal, and 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 parameterless read-only list operation with an output schema available, the description covers everything needed: what is listed, whose KBs are included, and what attributes are returned. There are no parameters to document and no hidden invocation requirements to infer.

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

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

The tool has zero parameters, so the baseline is 4; there is nothing for the description to add about argument semantics. The schema already records an empty parameter set with 100% 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?

The description uses a specific verb ('List'), names the resource ('knowledge bases'), and sharply defines scope: KBs you own plus organization KBs you belong to. It also enumerates the returned fields, which distinguishes it from sibling tools like findagent_list_kb_documents and findagent_list_kb_attachments.

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 makes the applicability clear by stating the ownership/membership scope, so an agent knows exactly what set of knowledge bases this tool covers. It does not explicitly name alternatives or state when-not-to-use it, but for a read-only listing tool with distinctive scope this is sufficient.

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 supply readOnlyHint=true; the description adds useful context beyond that by noting that active membership is the access requirement, and that org identification can be via org_id or slug. This goes beyond the structured annotation without contradicting it.

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 carry all essential information with no filler. The primary action and returned fields are front-loaded, with access and identification details placed afterward.

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

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

With an output schema present and read-only annotations set, the description covers the main behavioral requirements. A small gap: the schema marks both params as optional, but logically at least one of org_id or slug must be supplied; the description does not explicitly state this precondition.

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

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

Schema coverage is 100% with both parameters already described in the input schema. The description's note to identify the org by org_id or slug merely restates that guidance, adding no new semantic value.

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

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

States a specific verb ('List'), resource ('an organization's members'), and the returned fields (user id, role, status, joined date). This cleanly distinguishes it from member-mutating siblings like findagent_change_member_role and findagent_remove_member.

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

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

Clearly scopes when to use the tool: reading an org roster, with the permission note that any active member may read it. It does not explicitly name alternatives or when not to use it, but the resource and verb make the context unambiguous.

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

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

Annotations already carry readOnlyHint=true, but the description adds substantial context: what fields are returned per scope, that acquired agents are 'not yours to edit', and the re-version status inclusion. This is behavioral info beyond the annotation layer.

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

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

It is front-loaded with the core distinction and every clause earns its place, but the long parenthetical chains and stacked tool name lists make it dense and slightly run-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?

With an output schema present, return values need not be detailed, yet the description still summarizes them. For a single-enum-param listing tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the enum is documented in the schema, so baseline is 3. The description goes further by tying each scope to its purpose (editable via lifecycle tools vs. read-only library vs. both), adding meaning beyond the enum labels.

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+resource (list your agents) and immediately disambiguates 'yours' into created vs. acquired vs. all. It clearly separates itself from siblings like findagent_browse_agents and findagent_get_agent by scoping to ownership.

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

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

It gives explicit when-to-use routing: 'call it FIRST when you need a slug' for five named lifecycle tools, use scope:acquired when a buyer asks what they have access to, and use it after reconnecting in a new session. Alternatives and conditions are named directly.

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 provide readOnlyHint and openWorldHint, so the READ-ONLY note adds little new information. The description contributes the 'active member' filter and role/seat-count fields, which is useful context, but it does not disclose pagination, ordering, or failure behavior. This is acceptable for a zero-parameter read-only list 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?

The description is a single front-loaded sentence that states the action, scope, and returned fields with no filler. The redundant READ-ONLY note does not meaningfully hurt 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 zero parameters and an output schema handling return values, the description covers everything an agent needs in order to invoke the tool correctly. It specifies what entities are listed, the membership criterion, and the key fields returned.

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 input schema has zero parameters, so the baseline is 4; the description has no parameter semantics to add. There is nothing unclear about invocation inputs.

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

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

Uses a specific verb ('List') and resource ('organizations you are an active member of'), and adds concrete output details: role and seat count. The 'active member' scope also clearly differentiates it from related tools like findagent_get_org or findagent_list_members.

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 makes the context clear: use this when you need a read-only view of your active org memberships with your role and seat usage. It does not explicitly name alternatives or exclusion conditions, but the scope is evident enough for an agent to distinguish it from sibling org-related tools.

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 openWorldHint, but the description adds substantial context: it guarantees the tool never returns the GitHub token, and it discloses the two failure/edge-case responses (connected:false and needs_install). This provides valuable behavioral transparency 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?

The description is compact yet information-dense: purpose is front-loaded, followed by return fields, the next step, edge cases, and a security note. Every sentence adds value 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 zero-parameter, read-only tool, the description covers all necessary aspects: what it returns, how to proceed, error cases, and a security guarantee. It is complete enough for an agent to call it correctly and interpret the response.

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 input schema has zero parameters, so there is nothing to document. The description does not repeat schema info but instead focuses on output fields (full_name, default_branch, private flag) and behaviors. Given the baseline for zero parameters is 4, this is appropriate.

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

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

The description clearly states the verb (list), resource (the caller's own GitHub repos), and the intended purpose (to pick one to import). It also differentiates from siblings like findagent_connect_github and findagent_import_repo by explicitly mentioning the import flow.

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

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

It explicitly says to pass the chosen full_name to findagent_import_repo, establishing the workflow. It also provides guidance for edge cases: if GitHub is not connected, it points to findagent_connect_github; if no repos are granted, it mentions needs_install with an install URL. This helps the agent decide when to use this tool and what to do next.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'READ-ONLY.' It adds meaningful behavioral detail: mine:true includes withdrawn/removed rows that are flagged, status is ignored in mine:true mode, and the board matches the website /requests page. This goes well beyond structured fields.

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

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

The description is dense but every sentence carries information: resource, return fields, workflow, mine variant, filters, pagination, and read-only status. It is front-loaded with the most important scoping information and contains no filler.

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

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

Given the output schema exists, the description fully covers what the tool returns and all key behaviors. It explains the public vs. mine distinction, filtering options, pagination, and the relation to withdrawal. Nothing an agent needs to use it correctly seems missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds extra semantic value by explaining the mine:true behavior (including withdrawn/removed rows) and tying pagination to offset. Some details duplicate schema text, but the additional context earns a 4.

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

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

The description names a specific verb ('Read'), a precise resource ('PUBLIC FindAgent Agent Request Board'), and explains the board's nature with an example. It clearly distinguishes this from sibling tools by specifying the board scope and contrasting public vs. mine view.

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 describes when to use the public board vs. mine:true, and even points to findagent_withdraw_request for a related action. The context for filtering, sorting, and pagination is directly actionable without requiring inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context beyond those: the vocabularies are controlled and enrichment-oriented, and unknown slugs are silently dropped. This helps the agent understand consequences without contradicting 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?

The description is compact and front-loaded: it states the core purpose in the first sentence, then gives usage instructions and alternatives in two short follow-up sentences. Every sentence earns its place with no wasted words.

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 the zero-parameter signature, the read-only annotations, the existence of an output schema, and the presence of a named wizard alternative, the description covers everything an agent needs to decide to call it and to use its results 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter detail to document. The description still adds semantic value by explaining how returned slugs should be used in create_draft, which aids the agent even without parameters.

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

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

The description starts with a specific verb and resource: 'List the controlled Tech Domain and Language/Framework vocabularies'. It identifies the exact content of the tool—software-development discipline facets—making its purpose unmistakable and distinguishing it from generic listing tools.

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 explicit usage direction: 'Pass chosen slugs as create_draft tech_domains[] / languages[]'. It also names a preferred alternative, findagent_submission_wizard, and clarifies that unknown slugs are dropped, which tells the agent when to use this tool versus a guided walkthrough.

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 carry readOnlyHint=false and openWorldHint=false, so the description carries the full burden of behavioral disclosure. It delivers rich context: owner-only access, entry into the normal review gate, the listing-owned version rule ('never to a version declared in a repo'), and per-kind handling (re-pull, re-scan, re-version). This goes well beyond the sparse annotations.

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

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

The description is long but well-structured, front-loading purpose and usage before detailed per-kind behavior and parameter notes. Most sentences earn their place, though the extraneous mention of non-schema fields adds noise and the length could be tightened without losing meaning.

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 multi-kind, owner-only mutation tool, the description covers routing, ownership, review gate, version ownership, and sibling preference; output schema and full parameter descriptions fill the rest. The only substantial gap is the discrepancy between mentioned fields and the actual schema, which leaves a minor hole in the invocation contract.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds useful conditionality (ref only for code-bundle/skills-bundle, changelog 'where the kind takes one', bump default patch) but also references fields (system_prompt, tools, guardrails, etc.) that are not present in the input schema. This mismatch can mislead an agent into attempting unsupported parameters, offsetting the added value.

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

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

The description opens with a clear verb-resource statement ('Publish a NEW VERSION of YOUR OWN agent') and immediately establishes scope by covering all agent kinds. It explicitly names and contrasts with sibling tools (findagent_bump_version, findagent_repull, findagent_reintrospect_mcp), so an agent can disambiguate this tool without inspecting 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?

It gives explicit when-to-call guidance ('Call this when a creator asks to update, re-publish, re-pull, re-scan or bump their agent') and explains the key simplification ('you do NOT need to know which mechanism its kind uses'). It also explicitly states preference over three alternatives and the reason they are inferior, making the routing decision unambiguous.

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

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

The description discloses the asynchronous build ('build_status: 'building''), the need to re-call for final results, the advisory non-blocking nature of smoke, and the server-side blocking behavior. These details go well beyond the annotations and are consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=false; no contradiction exists.

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

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

The description is dense but front-loaded with the core purpose and returns. It earns most of its length by explaining asynchronous behavior, smoke semantics, and blocking rules, though the single long paragraph is slightly run-on and repeats some smoke wording already present in the schema.

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

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

For a complex gating tool, this description is complete: it explains where the tool fits in the workflow, what blocking vs advisory means, how async builds behave, how smoke is gated on build success, and what prerequisite input is required. The output schema covers return-value details, so 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?

The input schema already documents both parameters, so the baseline is 3. The description adds useful context beyond the schema: it emphasizes that the draft must be YOUR OWN, and it clarifies that smoke exists to confirm the agent 'actually responds with the credentials you saved' after the build passes.

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 starts with a specific verb and resource: 'Validate YOUR OWN draft BEFORE submitting it' and ties the tool to the submit gate. It clearly distinguishes preflight from submit and status siblings by explaining it surfaces the same checks before they would block submission.

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

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

It explicitly states when to use the tool ('BEFORE submitting', 'fix issues first') and the consequence of skipping it: 'Submit ... is blocked server-side until this passes.' It also gives granular usage conditions, such as the code-agent build path, optional smoke runs, and the need to pass a draft slug or id.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, but the description adds substantial behavioral context: the sandbox-gated SSRF-hardened scan, the fact that the live listing keeps serving until approval, the no-op on unchanged tools, the auth-required disclosure correction, and the 'nothing executes on FindAgent' safety note. This goes well beyond what annotations provide.

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

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

The description is dense but well-organized, front-loading the core action and then covering edge cases. Every sentence earns its place, though the length is substantial. It could be slightly trimmed, but the density is justified by the tool's complexity.

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 the tool's complexity, the description covers all critical behaviors: the scan, the comparison, the version submission, the no-op case, the auth-required case, the unreachable-remote case, ownership, and the distinction from siblings. The output schema exists, so return values need not be described. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the default bump (patch), the changelog override limit (≤500 chars), and the ownership requirement for slug. It doesn't add syntax details, but the schema already covers those; the description's extra context earns a 4.

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 ('Publish a NEW version... by RE-INTROSPECTING its remote endpoint'), names the resource (your own published external MCP-server listing), and clearly distinguishes it from siblings like findagent_bump_version and findagent_repull. It also explains the no-op case and the auth-required case, so an agent can tell exactly what this tool does.

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 explicitly says when to use it (owner-only, external mcp-server listings only) and when not to (code agents use the code wizard, doers use findagent_bump_version). It also states the optional parameters and the default behavior, leaving no ambiguity about 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 mark this as destructive (destructiveHint=true, readOnlyHint=false), and the description aligns with that. Beyond annotations, it adds meaningful behavioral context: permission requirements, role-based removal restrictions, and the last-owner safeguard, which help the agent anticipate failure cases.

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 entire description is a single, tight sentence with parenthetical constraints that carry high-signal information. Every phrase earns its place: the action, the permission gate, and the critical edge case.

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

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

For a destructive membership-removal tool with an output schema and complete parameter documentation, the description covers the key operational constraints: who may act, who may be removed, and the protected last-owner case. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and their sources. The description does not add parameter-level detail beyond that, which is acceptable given the schema's completeness; 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 clearly states the action ('Remove a member') and the object ('from an organization'), which immediately distinguishes this from sibling tools like invite_member or change_member_role. It also adds precise access constraints that clarify the tool's specific 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?

The description gives clear context on when this tool applies by specifying owner/admin permissions and noting that only an owner may remove an admin or owner. It also gives an exclusion, 'last owner cannot be removed'. However, it does not explicitly name alternative sibling tools or state when to prefer them over this one.

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

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

The description discloses the full pipeline: re-fetch, re-snapshot, re-scan, rebuild for code bundles, diff against live version, submit for review if changed, no-op if unchanged, and 'Your LIVE version keeps serving until the new one is approved (never auto-unpublished).' It also explains the non-obvious version-numbering rule (listing version + bump, not repo version), going well beyond the readOnly/destructive hints.

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 long but dense; the core action and scope are front-loaded in the first sentence, and the later paragraphs cover genuinely non-obvious behavior (version numbering, admin review, no-op). A small amount of ref/slug detail duplicates the schema, so it is not maximally concise.

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