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?

The description discloses the crucial non-obvious trait: despite the word 'Add', the tool only returns configuration and the actual install is deferred until the user signs in. It also reveals the conditional result modes (purchase_required, needs_input) and the exact contents of the returned config. This aligns with readOnlyHint=true and adds substantial value beyond the annotation.

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

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

The purpose is front-loaded in the first sentence, and each subsequent sentence carries a distinct, valuable detail (return items, entitlement rules, error outcomes, config-only caveat). At five sentences it is longer than the minimum, but the density of behavioral nuance 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?

The description covers entitlement rules, free vs paid scenarios, unknown slug handling, return contents, and the fact that installation is deferred to sign-in. Together with the existing output schema and annotations, an agent has all needed information to decide when and how 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?

Schema coverage is 100% and the slug's schema description already identifies it as a published agent slug from findagent_browse_agents. The tool description adds context about slug use in the URL and validation behavior, but no additional syntactic or formatting details for the parameter itself. With full schema coverage, 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 verb ('Add'), resource ('published FindAgent agent'), and scope ('entitled to'), and details what the tool returns. It distinguishes itself from findagent_browse_agents and findagent_buy_agent through the conditional routing of results, but it does not explicitly contrast with the similarly named findagent_create_remote_mcp, so it stops short of full sibling differentiation.

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

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

The description provides clear context for when to call this tool: the agent must be published and the caller entitled (free or paid/purchased). It also routes edge cases to alternatives ('purchase_required' points to findagent_buy_agent; 'needs_input' points back to findagent_browse_agents), effectively giving condition-based guidance. It lacks an explicit exclusion like 'do not use for arbitrary remote MCP servers', which would make it 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?

The description discloses several non-obvious behaviors beyond annotations: asynchronous ingestion pipeline (parse → structure-aware chunk → embed with the KB’s bound key), hash-based deduplication with the `deduped` response flag, and the silent failure mode when no embedding key is bound. The readOnlyHint=false annotation agrees with the mutating nature of the tool, so there is no contradiction.

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

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

The description is front-loaded with the core action and then efficiently adds async behavior, deduplication, embedding-key requirement, and file exclusion. Each sentence carries distinct information and no sentence feels redundant or padded.

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

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

For a 3-parameter tool with an output schema, the description covers the full operational context: how ingestion works, how duplicates are handled, what could cause failure, and when to use a different upload path. The agent has enough information to invoke the tool correctly and interpret likely outcomes.

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 (text, kb_id, title) sufficiently. The description adds contextual preconditions like KB ownership and bound embedding key, but it does not materially extend parameter-level semantics beyond what the schema provides. 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 opens with a specific action — 'Add a text document to a knowledge base you own by pasting its content' — which names the verb, resource, and input method. It clearly distinguishes this from sibling tools like findagent_delete_kb_document and findagent_list_kb_documents by restricting scope to adding text content only.

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 states exactly when to use the tool: for pasted text documents in a KB you own. It gives a concrete exclusion — for files (PDF/markdown/docx), use the web Knowledge Base uploader — and notes the prerequisite that the KB must have an embedding key bound. This is explicit when/when-not guidance.

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

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

Annotations only indicate readOnlyHint=false and openWorldHint=false; the description adds substantial behavioral context: how each mode behaves, that org KBs are auto-available, and that attaching is not part of the agent manifest so re-publishing is unnecessary. This meaningfully clarifies side effects 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 and well-structured: primary action first, then target identification, then mode choices, then an important caveat. Every sentence contributes needed decision-making information, with no filler or redundancy.

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

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

Given the tool's complexity (multiple target kinds, ownership rules, three modes, and an output schema), the description covers the key operational aspects: prerequisites, target lookup, mode effects, and manifest behavior. The output schema handles return values, so nothing critical 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 useful semantics by explaining mode meaning ('tool', 'auto_inject', 'both'), recommending target_slug over target_id, and clarifying target source tools. This goes beyond the schema's terse parameter comments without repeating them unnecessarily.

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 ('Attach') and resource ('a knowledge base'), and enumerates the possible targets (agent, department, org, personal). It also declares ownership/admin prerequisites, which distinguishes it clearly from related siblings like findagent_detach_kb, findagent_create_knowledge_base, 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?

It gives clear context for when to use the tool, including how to identify targets via findagent_list_my_agents or findagent_list_orgs and the ownership requirements. It does not explicitly name sibling tools as alternatives or state when not to use it, but the context is strong enough for an agent to select it appropriately.

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 description doesn't need to state it. It adds behavioral details beyond the schema: that it is the same store listing as the website, that it includes pricing, and how pagination works (next_offset, has_more). No contradictions 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 moderately long but every sentence contributes: purpose, return fields, filters, pagination, and alternative tool. It is front-loaded with the core purpose, and the structure flows logically. Slightly more detail than necessary, but not wasteful.

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 doesn't need to detail returns, but it does anyway. It covers all filter options, pagination, and the alternative for single-agent views. An agent has everything it needs to call and iterate 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. The description adds extra meaning by noting category_slug comes from findagent_list_categories (not mentioned in schema), and reiterates the pagination flow (use returned next_offset) which is also in the schema. This additional context makes it more helpful than a bare 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 clearly states the verb ('Browse'), the resource ('PUBLISHED FindAgent marketplace catalogue WITH pricing'), and explicitly differentiates from the sibling tool findagent_get_agent ('for the full store view of one slug'). It also includes the exact fields returned, leaving no ambiguity about what the 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?

Provides explicit when-to-use guidance: it is the catalogue browser, and explicitly points to findagent_get_agent for a single agent. It also tells users where to obtain category_slug (from findagent_list_categories) and gives precise pagination instructions (use next_offset, repeat until has_more is false). No ambiguity left for the agent.

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

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

The description 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?

Beyond the annotations, the description reveals key behavioral details: it returns a checkout URL, payment is handled by Paddle in the browser, card details should never be shared in the tool, and several possible return states (already_free, already_owned, checkout_not_live) are disclosed. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

The description is dense but every sentence serves a purpose: defining the action, explaining the browser flow, warning against sharing card details, and enumerating the distinct output states. The most important information is front-loaded.

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

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

For a single-parameter tool with an output schema present, the description covers the input origin, the browser-based payment flow, post-purchase next steps, and all relevant status outcomes. An agent has enough context to invoke it correctly without further investigation.

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 has a single parameter with full coverage, so the description is not required to compensate. It still adds marginal value by clarifying the slug comes from findagent_browse_agents, but it does not need to go further.

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 phrase 'Get a browser checkout link to PURCHASE a paid FindAgent agent' states a specific verb, resource, and outcome. It is clearly differentiated from related tools like findagent_add_connector and findagent_browse_agents based on the purchase-oriented 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 explicitly gives routing guidance: use findagent_add_connector for free agents, retry it after a paid purchase settles, and fall back to findagent_browse_agents for unknown slugs. This makes the when-to-use decision explicit rather than implied.

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

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

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?

The description discloses the persistence behavior ('status=draft agent owned by you') and the required follow-up workflow, which goes well beyond the annotations. It also adds behavioral nuances such as invalid metadata blocks being dropped, invalid guardrails failing the draft, and credential_slots being shape-only declarations. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

The core purpose is front-loaded in the first sentence, and every subsequent sentence earns its place: sibling routing, preflight checks, follow-up steps, and a security warning. Despite its length, the density of actionable guidance is justified by the 21-parameter surface area.

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 gives a complete operational context: where the draft comes from, which sibling tools to use before and after, how to structure credential declarations, and which preconditions to verify. Since an output schema exists, the description need not explain return values, and nothing needed 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?

Although schema coverage is 100% and the baseline is 3, the description adds crucial inter-parameter semantics: kind is inferred from tools, title accepts the alias name, credential_slots must not contain secret values, auth_ref must match allowed_hosts, and category selection has discipline/subcategory constraints. These relationships are not fully obvious from the schema alone.

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: 'Persist a DRAFT marketplace listing' and 'Creates a status=draft agent owned by you.' It differentiates itself from siblings by explicitly naming findagent_submit_for_review and findagent_submission_wizard as separate steps/tools, so an agent can tell exactly what this tool alone accomplishes.

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 guidance is given: prefer findagent_submission_wizard first, use findagent_check_slug and findagent_list_categories before calling, then call findagent_submit_for_review in the MCP client. It also clarifies that the web is only an optional preview, not where completion happens, and states a hard security rule about never sending secret values.

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?

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 convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavioral context: the operation is owner-gated, recorded to an audit log, not retroactive for existing buyers, and follows the same validated path as the web price editor. This goes well beyond the structured annotations.

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

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

Three dense sentences with no filler. The action, scope, required parameters, constraints, and side effects are all front-loaded and each sentence adds necessary 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?

Given the rich annotations, complete input schema, and presence of an output schema, the description covers everything an agent needs to invoke it correctly: ownership, price bounds, paid/free behavior, non-retroactivity, and audit logging. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description mostly restates schema information, though it does add the convenient '$500' equivalence and reinforces the 'ignored for free' behavior. With full schema coverage, 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 opens with a specific verb and resource: 'Change the price of YOUR OWN agent'. It clearly differentiates from sibling tools like findagent_buy_agent (purchase) and findagent_edit_metadata (other metadata) by naming the exact operation and 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?

It gives clear usage context: only the agent's owner can call it, price_type must be 'free' or 'paid', and price_cents is only needed when paid. It doesn't explicitly name alternatives or when-not conditions, but the ownership and scope constraints make appropriate usage 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/openWorldHint annotations, it discloses a non-obvious outcome: paid agents hide their tools/skills until purchase. It also specifies the needs_input result for invalid slugs and routes to browse_agents, which is exactly the kind of behavioral context an agent needs.

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

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

The description is front-loaded and dense, with purposeful caveats and error behavior. The enumerated return fields are useful but partly redundant with the existing output schema, so a touch of trimming would make it fully lean.

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 read tool with an output schema, nothing important is missing. Valid input source, expected scope, hidden-content caveat, and invalid-slug behavior are all covered.

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

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

Schema coverage is 100% and already explains the slug and its source, so the description adds little to parameter understanding. It reinforces that the slug must be published, but that is also already implied by 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 opening clause names a specific verb and resource ('Get the full store view of ONE published FindAgent marketplace agent by slug') and distinguishes it from browsing/list siblings. It also lists the returned fields, so an agent immediately understands the tool's scope and output focus.

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 tells the agent the slug must come from findagent_browse_agents and describes the fallback when a slug is unknown or unpublished. It does not explicitly enumerate when-not-to-use or name an alternative, but the by-slug scope makes the intended context 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?

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 declare readOnlyHint=true, and the description adds 'READ-ONLY' plus the ownership scoping ('Only agents/departments you own are returned') and the presence of in-flight re-version status. This goes well beyond the annotation and clarifies exactly what data the agent can expect, especially the ownership restriction.

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 core purpose is front-loaded, the ownership constraint is in the second sentence, and the usage guidance is compact but specific. The list of sibling tools is dense but directly actionable, making the description efficient rather than verbose.

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 with an output schema, the description is complete: it tells the agent what it returns, when to use it, and what not to expect (only owned resources). Nothing necessary 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 tool has zero parameters, so there is nothing to document; the baseline for 0 parameters is 4. The description properly focuses on output content rather than parameters, which is appropriate here.

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

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

The description uses a specific verb-resource pair ('List YOUR OWN agents') and enumerates the returned fields (id, slug, name, kind, status, in-flight re-version status), plus personal departments. It also distinguishes itself from sibling tools by emphasizing 'Only agents/departments you own are returned', which separates it from browse/list-all 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?

Explicitly states when to call this tool FIRST: when needing a slug for lifecycle tools, to submit a draft, or to attach a knowledge base, and after reconnecting in a new session. It names concrete sibling tools as destinations, giving the agent unambiguous routing guidance.

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

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

Annotations already 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?

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?

Goes far beyond the annotations: describes sandbox-gated SSRF-hardened scanning, that the live listing never gets auto-unpublished, that unchanged tools produce a no-op, and that unreachable/auth-walled endpoints leave state unchanged. Also clarifies nothing executes on FindAgent and that a new version goes to admin review. No contradiction with readOnlyHint=false and destructiveHint=false.

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

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

Dense but front-loaded: the first sentence states the exact operation and object, and later sentences each add a distinct behavioral constraint (no-op, no auto-unpublish, auth-wall failures). Length is justified by the number of safety-relevant details; no filler or redundancy.

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

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

Given the tool's complexity (review workflow, no-op, failure modes, ownership, compatibility scope) and the presence of an output schema, the description covers every decision-relevant dimension. An agent can determine whether to call it and what will happen in all named outcomes.

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 already covers all 3 parameters at 100%, so baseline is 3. Description adds useful nuance: slug must be owned, server URL is read from the stored listing, bump defaults to patch, and changelog overrides the auto-draft. This lifts it above baseline.

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

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

Clearly identifies a specific action: publish a new version of an external MCP-server listing by re-introspecting its remote endpoint. It distinguishes from sibling tools like findagent_bump_version (for doers) and the code wizard, and references the owned-slug requirement. 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 explicit applicability: owner-only, external mcp-server listings only, and explicitly routes code agents to the code wizard and doers to findagent_bump_version. It also describes no-op and failure conditions that tell the agent when calling is pointless (unchanged tools, unreachable remote). This is strong alternative-routing guidance.

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

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

Annotations already 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 important behavioral details not captured by annotations: the repo is re-fetched/re-snapshotted/re-scanned/re-built, a new version is submitted for admin review only if changed, the live version keeps serving until approval, and it never auto-unpublishes. These are exactly the kinds of side effects an agent needs to know about.

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

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

The description is dense and front-loaded with the core purpose, then walks through process, safety behavior, and exclusions. It is longer than minimal, but the tool is complex and nearly every sentence contributes useful decision-relevant information; minor redundancy exists in the ownership and repo-pinning statements.

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 is complete: it covers when it is a no-op, what happens on change, review submission, live-version behavior, ownership constraints, repo pinning, and alternative tools. Since an output schema exists, the absence of return-value detail is not a gap.

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

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

Schema description coverage is 100%, so the schema already documents the slug, ref, and bump parameters thoroughly. The description adds some contextual framing for slug ownership and ref defaults, but does not materially extend parameter-level meaning beyond the schema.

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

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

The description names the specific action ('Publish a NEW version... by RE-PULLING'), the resource ('your own published CODE-BUNDLE or SKILLS-BUNDLE agent'), and the source ('OAuth-connected GitHub repo'). It also distinguishes itself from nearby flows by explicitly stating it is not for doers/recipes or external MCP listings.

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 says when to use this tool and explicitly names alternatives: doers/recipes use findagent_bump_version and external Mcp-server listings use findagent_reintrospect_mcp. It also gives clear conditions for behavior — only if the repo changed, and no-op in unchanged — and constrains usage to owned code-bundle or skills-bundle agents.

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

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

Beyond the annotations, the description discloses the key observable behavior: the live agent immediately serves the earlier version, existing buyers retain access because entitlement is per purchase not per version, and unreviewed content can never be served. It also states the owner-only authorization requirement. This adds strong 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 front-loaded with the core action and packs the important procedural and safety guidance into three sentences. There is slight redundancy around 'published' and 'already-reviewed,' but every sentence contributes necessary information and there is no filler.

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

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

For a two-parameter tool with a 100% schema description, an output schema, and clear annotations, the description covers the complete call flow, ownership constraint, eligibility rule, and side-effect behavior. An agent has everything needed to invoke the tool correctly in both of its modes.

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's workflow instructions, such as 'OMIT `version` to LIST the prior published versions,' largely restate what the version parameter schema already says ('Omit to list the eligible targets first'). It adds safety context about prior published versions, but this does not substantially deepen the meaning of the individual parameters 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 opens with a specific verb and resource: 'Roll YOUR OWN PUBLISHED agent BACK to a prior version.' It clearly identifies the operation, the required ownership, and the distinction between listing candidate versions and performing the rollback. No sibling tool matches this exact purpose, so it is sufficiently differentiated.

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

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

The description gives a clear two-step usage pattern: omit `version` to list eligible targets, then call again with `version` set to one of them. It also states when-not: only previously published versions are valid targets, and only the owner can perform the action. It does not explicitly name alternative sibling tools such as bump or withdraw, so it falls short of a 5, but the guidance is otherwise explicit and actionable.

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, public catalog.' It adds context about the catalog being public and the exact output structure (title + snippet + id), which goes beyond the annotations. No contradictions exist. The description does not cover potential rate limits or auth, but for a read-only search tool the annotations and output schema cover the essential behavior.

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

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

Two sentences with zero waste. The first sentence states the purpose and the critical exclusion (NOT private KBs), and the second describes the return and usage. All information is front-loaded and 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 simple read-only search tool with a rich output schema and clear annotations, the description is fully adequate. It covers what the tool searches, what it excludes, what it returns, and how to use it. No missing information would prevent an agent from calling 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%, with both 'query' and 'limit' having clear descriptions. The description does not add any parameter-specific details beyond what the schema already provides, so it meets the baseline for a tool with full schema coverage. No additional value is needed here.

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

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

The description uses a specific verb ('Search') and resource ('FindAgent curated skill catalog') and explicitly differentiates from private knowledge bases, making the tool's purpose unmistakable. It also states the return format (title + snippet + id), which helps the agent understand what to expect. No sibling tool is similar enough to cause confusion.

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 this tool: for platform-wide public catalog guides, not private knowledge bases. It also hints at the use case (grounding an answer). However, it does not name specific alternative tools for private KBs, so it stops short of fully explicit routing. The exclusion is clear, but the alternative is implied rather than stated.

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

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

The readOnlyHint annotation is reinforced and enriched: the description spells out READ-ONLY, owner-only scope, the returned statuses, in-flight version, reviewer needs-changes reason, and security-scan findings. This goes well beyond the annotation and tells the agent exactly what to expect from the call.

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 without fluff: purpose, payload contents, usage timing, owner restriction, and safety hint all appear in a compact block. The most important scoping phrase ('YOUR OWN agent') is front-loaded, and 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 read-only tool with an output schema, the description is fully sufficient. It covers what the tool does, what it returns, when to call it, and who can call it, leaving no practical ambiguity for an agent selecting or invoking the 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?

With 100% schema coverage, the schema already documents the sole 'agent' parameter as a slug or id. The description repeats 'Pass the agent slug/id' and adds 'YOUR OWN agent', which is slightly clarifying but largely redundant with the schema and sibling context.

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: 'Check the review status of YOUR OWN agent and WHY it is where it is'. It lists the exact statuses and names findagent_submit_for_review as its companion, clearly distinguishing this tool from submission and general browsing 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 says to use this after submitting, describes what conditions it reports (approved, still in review, sent back), and adds the owner-only restriction. It does not explicitly discuss when not to use it versus other status/query tools, but the 'YOUR OWN agent' scope and companion reference make the usage context 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 indicate readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds behavioral context beyond annotations by stating that the tool returns steps and choices, that repo/source hints are echoed back only, and that it does not actually pull a repository. This is useful but not exhaustive.

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

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

The description is information-dense but every clause earns its place: purpose, output, interaction pattern, validation step, finalization step, and exclusion of repo pulling. It is front-loaded with the core purpose 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?

The description is complete for a wizard tool: it explains what is returned, how the agent should guide the user, which sibling tools to use for validation and finalization, and what the optional parameters do not do. The presence of an output schema further reduces the need to describe return values in the description.

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 documented. The description adds value beyond the schema by clarifying that repo/source hints are only echoed back and that the tool does not perform a repo import, which prevents an agent from assuming side effects.

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 action and resource: 'Start a guided, step-by-step submission wizard' and immediately defines the key output: ordered steps plus selectable choices. It also distinguishes itself from related tools by explicitly saying it does not pull a repo and that repo import belongs to findagent_import_repo.

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: prefer this over asking for all listing fields at once, ask one step at a time, validate slugs via findagent_check_slug, and finalize with findagent_create_draft. It also names findagent_import_repo as the correct alternative for repo pulling, giving 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.