FindAgent

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

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

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

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

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

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

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

For a one-parameter tool with an output schema, the description covers what the tool does, where the token comes from, and the key failure conditions. Nothing essential is missing for an agent to invoke it correctly.

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

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

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

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

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

The description states a specific verb and resource: 'Accept an organization invite' using the invite token. It also adds a key scoping detail—binding to the authenticated FindAgent email—which distinguishes it clearly from sibling tools like invite_member or leave_org.

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

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

The description makes the intended use clear: call this when you have a token from an organization invite link. It does not explicitly name alternatives or exclusions, but the action is unique enough among siblings that the context is sufficient.

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

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

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

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

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

Dense but front-loaded: capability first, then return payload, then failure modes, then the external-server caveat. Every sentence carries information, though the four-sentence run-on covering entitlement and error states could be tightened slightly for scanning.

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

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

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

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

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

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

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

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

States a specific verb and resource ('Add a published FindAgent agent ... as a hosted MCP connector') and immediately scopes it by entitlement. It also names the sibling tools it is not (findagent_browse_agents for discovery, findagent_buy_agent for purchase), so an agent can route correctly without opening another schema.

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

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

Explicit when-to-use and when-not-to-use: free agents always work, unowned paid agents return purchase_required pointing at findagent_buy_agent, unknown/unpublished slugs return needs_input pointing at findagent_browse_agents, and MCP server listings take a different path entirely. The alternative tool for each blocked case is named.

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

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

Annotations only say readOnlyHint=false and openWorldHint=false. The description goes well beyond them: asynchronous ingest pipeline (parse → structure-aware chunk → embed with the KB's bound key), hash-based de-duplication where re-adding is a no-op surfaced via the `deduped` flag, and the embedding-key precondition. This is exactly the extra behavioral context annotations cannot carry.

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

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

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

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

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

For a write tool with an output schema already present, the description fills in what the structured fields do not: the async ingest model, dedup semantics and its response flag, the embedding-key precondition, and the file-vs-text boundary. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents text (plain text, max 1 MB), kb_id (from findagent_list_kbs), and the optional title default. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Puts CONTENT INTO a knowledge base' / 'Add a text document'), and explicitly names the sibling it is not — findagent_attach_kb — plus the file-upload path. An agent can distinguish this from attach_kb and the uploader without opening any schema.

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

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

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

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond by disclosing the SSRF guard rules (https only, no redirects, public addresses only, size/time caps), the generic failure message and the absence of a bypass, the async parse→chunk→embed pipeline, the shared per-user import allowance, and the embedding-key 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?

Front-loaded with the core action and mechanism, and the dense clause runs (async pipeline, SSRF guard) each carry operational value rather than filler. It is long but justified by the tool's complexity, though slightly run-on.

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

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

An output schema exists, so return values need not be described. The description covers prerequisites, failure modes, async semantics, and constraints, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%, so url, kb_id, and title are already documented in the schema. The description reinforces that only https schemas are accepted and that the KB must be owned, but adds little parameter detail beyond the schema baseline.

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

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

States a specific verb and resource ('Add a document to a knowledge base'), the input mechanism (https URL), and the server-side behavior (fetch, extract, ingest asynchronously). It even names the sibling it differs from via the 'Add from URL' analogy, so an agent can distinguish it from findagent_add_kb_document without reading either schema.

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

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

Explicitly routes to the alternative: 'To paste text instead use findagent_add_kb_document.' It also states the precondition for success ('Requires the KB to have an embedding key bound, or the document will not ingest') and the constraint that the KB must be owned, giving clear 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?

Goes well past the annotations (destructiveHint/readOnlyHint) by disclosing concrete side effects: the connector, runs and schedules stop at once, nothing is hard-deleted, and the deletion is reversible via edit_department. This reversibility and the side-effect scope are exactly the context an agent needs for a destructive operation.

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

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

Four tightly packed sentences, front-loaded with the action and scope, then side effects, then ownership/precondition caveats. No sentence is redundant.

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

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

With an output schema present and annotations covering the safety profile, the description supplies everything else needed: what gets stopped, reversibility, ownership requirement, and org-department exclusion. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the single 'department' parameter is documented in the schema as a slug sourced from findagent_list_departments. The description refers to the handle/department but adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Delete/archive) and resource (PERSONAL department), and immediately scopes it to departments 'you own' versus organization departments. An agent can distinguish this from findagent_edit_department, findagent_create_department, and sibling delete tools without opening a schema.

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

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

Explicit when-to-use constraints: only personal departments, only by the owner, and an org department 'is not archived here'. It also explains the not-found outcome for non-owned handles and routes restoration to findagent_edit_department with status:"draft".

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

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

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

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

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

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

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

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

An output schema exists, so return values need not be described, and the definition still covers authorization, target identification, mode semantics, and a non-obvious deployment caveat. Sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what each mode value does operationally (tool grants a search_knowledge tool, auto_inject prepends passages), recommends target_slug over target_id, and clarifies omission of target fields for user_personal. This goes beyond the terse enum labels.

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

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

States a specific verb (connects/attaches) and resource (an EXISTING knowledge base) and explicitly scopes it against the sibling findagent_add_kb_document, which handles content addition. An agent can differentiate this from add_kb_document without opening either schema.

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

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

Gives concrete when-to-use conditions: attach a KB you own to an agent/department you own, to an org you administer, or as a personal KB. Names the exact lookup tools for each target type (findagent_list_my_agents, findagent_list_orgs) and states the auth requirement (org owner/admin). Nothing is left to inference.

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

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

Annotations only supply readOnlyHint=false and openWorldHint=false; the description goes well beyond, disclosing the re-queue side effect, the deliberate no-secret-in-arguments design, the no-op-and-report behavior when no key is stored, and the owner-only permission requirement. These are exactly the traits an agent needs before invoking a mutation.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds behavioral context: it is paginated, explains the offset/next_offset mechanism and has_more flag, and lists the exact return fields. It does not contradict annotations and discloses all relevant operational behavior without being redundant.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It gives a clear alternative: 'Use findagent_get_agent for the full store view of one slug,' which tells the agent when to prefer another tool. It also references findagent_list_categories for category slugs, but does not enumerate other exclusions (e.g., when to use findagent_list_my_agents). This is clear context with a single explicit alternative, but not exhaustive guidance.

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

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

Beyond the annotations, the description discloses the full behavioral workflow: the new version goes to admin review, the live version keeps serving until approved and is never auto-unpublished, a price change applies immediately but not retroactively, capability changes re-run the security scan and author-time auth_ref↔host check, and guardrails can only be tightened.

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

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

The description is long and dense, but it is front-loaded with purpose and required parameters, then moves through edit capabilities, review behavior, and routing exclusions. Almost every sentence adds operational value, though some parenthetical detail could be tightened.

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

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

Given the tool's complexity, 11 parameters, nested objects, and the existence of an output schema, the description is complete enough for correct invocation. It covers purpose, usage boundaries, mutation behavior, review flow, and security implications without needing to explain return values.

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 description coverage, the schema already documents most parameters, but the description adds real meaning: `tools` presence replaces the entire tool surface, `changelog` is optional when editing tools and otherwise must be 10–500 chars, `price_cents` requires `price_type=paid`, and `credential_slots` are definitions only. It does not mention the `llms` parameter, but the schema covers it.

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

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

The description uses a specific verb and resource: 'Publish a NEW version of YOUR OWN published agent built here (instructions, skills and actions) for review.' It distinguishes this tool from siblings by explicitly naming findagent_new_version and findagent_repull for repo-backed ACTION agents, and the code wizard for code-bundle agents.

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

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

It gives explicit when-to-use and when-not-to-use guidance: use this for an agent built here, but for a code-bundle agent use the code wizard, and for an ACTION agent whose findagent.json is in a writable GitHub repo call findagent_new_version or findagent_repull with `repo` instead. Owner-only is also 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 description goes well beyond the annotations, disclosing that payment is handled by Paddle in the browser, warning never to share card details, and enumerating possible return states such as already_free, already_owned, checkout_not_live, and needs_input. It also notes the authentication requirement (signed in to FindAgent), which is useful behavior context.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Three short sentences with no filler. The primary action is front-loaded, followed by the most important permission rules and a key business constraint. Every sentence earns its place.

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

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

The description covers the main operation, permission rules, and a critical invariant. An output schema exists so return values need not be described. One minor gap is that org_id/slug are optional in the schema and the description does not explicitly say one of them is required, but overall the tool is adequately specified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining role constraints and who can set which role, which directly informs how to fill the 'role' parameter. It could be more explicit about needing one of org_id/slug, but the constraint semantics are valuable.

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

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

The description uses a specific verb ('Change') and resource ('a member's role in an organization'), and immediately distinguishes the operation from related tools like invite/remove/transfer by stating the permission model. The scope is clear even without inspecting the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description uses a specific verb ('Check'), a clear resource ('agent slug'), and the exact criteria ('well-formed AND available'). It explicitly distinguishes itself from siblings by stating it runs 'before findagent_create_draft' and naming the recommended alternative findagent_submission_wizard. An agent can immediately understand the tool's function without any ambiguity.

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

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

The description provides explicit usage context: 'before findagent_create_draft' sets the timing, and 'Prefer findagent_submission_wizard' directly names the alternative and indicates it should be chosen over this tool in normal flows. This is a clear when-to-use and when-not-to-use directive, with a specific alternative named.

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

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

Goes well beyond the annotations by explaining the two proof mechanisms (admin GitHub account on a declared repo vs DNS TXT record on the endpoint host), that the listing chooses the proof, and that re-calling is idempotent so an existing record stays valid. This is exactly the side-effect and auth context an agent needs for a non-readOnly operation, matching idempotentHint=true 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?

Front-loads the action and its scope, then layers proof mechanics, the routing to verify_listing_claim, idempotency, and exclusions. Every sentence carries distinct information with no restatement of the name or annotations.

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

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

With an output schema present, the description needn't enumerate return fields, yet it still previews them ('returns which proof applies and, for DNS, the exact record name and value'). Combined with the idempotency and eligibility notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, including the 'give this OR agent_id' rule. The description adds the constraint that the target must be a published listing rather than an agent, but contributes no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('start/re-read a claim') on a specific resource ('an MCP server LISTING that you run'), and explicitly scopes it to LISTINGS rather than agents or other resources. An agent can distinguish it from findagent_verify_listing_claim, which is named as the follow-up step, without opening either schema.

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

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

Gives explicit when-to-use ('once the proof is in place, call findagent_verify_listing_claim'), what it does not do ('opening a claim grants nothing'), and an exclusion ('only published MCP server listings can be claimed, never an agent'). The alternative tool and the condition that selects it are both spelled out.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses server-side re-pull with the stored GitHub token, snapshot+scan+manifest validation, the resulting status=draft ownership, idempotency by repo with overwrite semantics and the `updated` flag, the prohibition on sending secret values, and that build/run stays gated until admin approval. This is unusually rich operational 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?

Purpose and trigger are front-loaded, but the body is a dense block that mixes invocation guidance with tangential material (GitHub template and agent-creators playbook URLs) that does not help select or call the tool. For a 21-param tool the length is largely justified, though trimming the trailing links would tighten it.

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

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

For a 21-parameter, nested-object, multi-step creation tool with an output schema, the description covers the full workflow (import grounding, override, idempotent overwrite, gated run, submit-for-review) plus the secret-value guardrail. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it groups the required basics, points out that the detected contract (runtime/entrypoint/mcp/ui/allowed_hosts/credential_slots/skills) comes from import_repo's grounding.code_bundle, and says you may override any field. It also flags that credential_slots declare shape only, reinforcing the schema's warning.

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 ('Persist a CODE-BUNDLE draft from YOUR OWN GitHub repo') and explicitly scopes it to agents shipping runnable code. It also names each sibling (findagent_create_package_draft, findagent_create_remote_mcp, findagent_create_draft) and assigns the distinct part each handles, so an agent can route without opening any schema.

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

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

Gives an explicit trigger ('use this when findagent_import_repo returned grounding.code_bundle') and an explicit alternative for every other case. It also spells out the follow-on step ('then call findagent_submit_for_review IN THIS MCP CLIENT') and notes the web is only an optional preview.

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

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

Annotations cover safety profile (not read-only, not destructive), and the description adds substantial behavioral context beyond them: report_instructions are 'scanned for secrets and prompt-injection phrasing before anything is saved,' the department is created as a personal DRAFT that is never published or reviewed, and it works only 'once its members are available.' This is exactly the kind of trait annotations cannot express.

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

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

Front-loaded with the core definition and required params, then progressively adds pattern semantics, the report_instructions side effect, the draft-only nature, and membership constraints. Dense but every clause carries information; slightly long for a description but 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?

Even with a rich schema and output schema present (so return-value explanation may be abbreviated), the description covers creation semantics, validation constraints, security scanning of report_instructions, the draft lifecycle, and hard refusals of unsupported modes. An agent has everything needed to call this correctly and to know what it should not attempt.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters including the hub/entry/alias/role defaults. The description adds marginal value by explaining pattern semantics ('pipeline members run in order', hub-orchestrator requires hub, p2p optionally entry) and the alias/role relationships, but largely reinforces existing schema text. Baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (department), immediately resolving the ambiguous term by defining it as 'a team of 2-16 EXISTING published agents with a topology.' This distinguishes it from sibling findagent_create_org (organization) and findagent_create_draft (single 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?

Provides clear preconditions (each member must be a published public agent; an OAuth-signin agent cannot be a member yet) and explicitly routes unsupported configurability to the web builder ('refused here, not ignored'). No explicit when-not-to-use against edit_department or create_org, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation class is known. The description adds genuinely new behavioral context: the created object is status=draft and owned by the caller, finalization must happen inside the MCP client rather than the web UI, and credential slots carry shapes only, never values. It does not cover reversibility or draft limits, so not a 5.

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

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

The core purpose and workflow are front-loaded, but the final two sentences (agent-template repo, AGENTS.md playbooks) read as build-time guidance belonging to other tools and dilute the instruction for an agent trying to call this one. Dense and useful overall, with avoidable tail bloat.

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 21-parameter, deeply nested creation tool with an output schema, the description covers prerequisites, sibling routing, sequencing, the paid/free and submission hand-off, and the secrecy rule for credential slots. 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?

Schema description coverage is 100%, so the baseline is 3, but the description does add semantic constraints beyond the schema: credential_slots are definitions only and are never populated with values, and completion of price/originality fields happens in submit_for_review rather than here. That mapping between fields and workflow steps is real value over the schema text.

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 ('Persist a DRAFT marketplace listing') and explicitly positions itself against four sibling creation tools (create_package_draft, create_code_draft, create_remote_mcp, import_repo grounding). An agent can select it without opening any schema.

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

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

Gives explicit ordering (check_slug, list_categories, then create, then submit_for_review IN THIS MCP CLIENT), names the preferred alternative (submission_wizard) and its benefit, and states the 'never send secret VALUES' exclusion. When/when-not/alternatives are all present.

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?

With only readOnlyHint=false/destructiveHint=false in annotations, the description carries the burden well: it discloses the skill cap (40, 'refused, never cut'), size caps (4 MB total, 2 MB per file, 4000 files, ~4.5 MB request), that binary files cannot be sent, that the package is stored in the caller's namespace as a status=draft listing, and that a human reviews before publication. It stops short of stating auth/permission requirements or what a partial failure returns, but this is unusually rich 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 core action is front-loaded in the first sentence, but the body is a single dense run-on paragraph mixing limits, workflow rules, tool-selection routing, and external template URLs. The trailing repository links (agent-template, agent-creators) are tangential to invoking this tool and dilute the payload.

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

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

For a 13-parameter, nested-object, write-operation tool, the description covers the input format, all hard limits, the attestation requirement, the draft state and ownership outcome, and the mandatory review step. Return values are not needed since an output schema exists.

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

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

Schema coverage is 62%, and the description compensates for the gap: it explains the `files` object shape (path -> full TEXT) with concrete example paths including plugin.json and commands/*.md, clarifies that listing fields come from the same source as findagent_create_draft while instructions/prompts/actions come from files, and reinforces the attestation enum value. It does not cover every listing metadata parameter (llms, tech_domains, tags), leaving some schema reliance.

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

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

Opens with a specific verb+resource: 'Create a DRAFT agent from an Agent Plugins package you wrote in this conversation.' It immediately distinguishes itself from the near-identically named siblings by naming them and the exact part each covers ('Instructions, Skills and Actions ... findagent_create_package_draft; Code ... findagent_create_code_draft; an MCP server ... findagent_create_remote_mcp').

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?

Includes an explicit 'Which tool for which part' decision table mapping each authoring input to the correct tool, states the required follow-up call (findagent_submit_for_review) and why, and notes the prerequisite attestation. An agent can select this tool vs its siblings without 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, but the description adds substantial context beyond them: the object is created as a status=draft, the server URL is 'stored + displayed only; nothing executes on FindAgent', tools are auto-detected via a sandbox-gated live scan with override capability, and auth_note must never carry a secret. This is rich, non-redundant 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 scoping statement and the create-vs-submit flow are front-loaded, and almost every clause carries information. It is dense and slightly run-on in the middle (the detection/override sentence), but nothing is filler.

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

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

For a 14-parameter tool with nested objects, enums, and an output schema, the description covers what the agent must know: draft state, non-execution guarantee, auto-detection vs override, secret-handling rule, and the mandatory next call. Return values are delegated to the output schema, which is correct.

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 meaning: it clarifies that server_url and server_json are alternatives, that example_prompts are 1-5 and required, that tools/transport/auth_note are overrides of auto-detection, and explains WHY category fields are ignored ('a listing is not categorised'). That reasoning goes beyond the schema's bare 'Ignored'.

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

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

States a specific verb+resource ('List an EXTERNAL remote MCP server ... as a marketplace LISTING') and crisply scopes it to MCP servers hosted on your own infrastructure that buyers connect to directly. It explicitly distinguishes itself from the draft/package/code-draft siblings by being the remote-MCP listing path, so an agent can pick it without opening schemas.

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

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

Explicitly says when to use it (external remote MCP server you host, never proxied by FindAgent), what it produces (status=draft agent you own), and the follow-up step ('call findagent_submit_for_review in this MCP client'). It also names prerequisites to run first (findagent_check_slug + findagent_list_categories).

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 give readOnlyHint=false and openWorldHint=false; the description adds real behavioral context beyond them — the request is public, moderated, always starts OPEN, free with no payment, and returns a new request id. It stops short of describing what moderation failure looks like or reversibility, so not a full 5.

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

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

Front-loaded with the core action and scope, then constraints, then return/usage. Every sentence carries information, though it runs several sentences and could tighten slightly.

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

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

With an output schema present, return values need not be detailed; the description still notes the returned request id. Public visibility, moderation, initial state, cost, and the routing trigger are all covered — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates the same constraints (title 5–120 chars, body ≤2000) with only a minor added nuance ('tools to connect, what a good result looks like' mirrors the schema), so baseline 3 applies.

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

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

States a specific verb+resource (post/create an agent request on the PUBLIC FindAgent demand board) and clearly frames it as 'I want an agent that does X', distinguishing it from browse/search and other create_* siblings.

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

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

Explicitly names the alternative moments to use it: 'A search that found nothing (findagent_browse_agents or findagent_skill_search with no match) is a good moment to offer this.' This ties the tool to a concrete trigger condition relative to named siblings.

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

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

Annotations declare destructive=true and readOnly=false, and the description goes well beyond them: it explains this is a soft-delete that renames the row to a discarded tombstone, that the original slug is freed immediately, and that it is owner-only. This is exactly the behavior an agent must know before invoking a destructive tool.

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

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

Three tight sentences, front-loaded with the action and constraint, then the mechanism, then the exclusion. Zero filler; every sentence carries decision-relevant information.

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

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

For a single-parameter destructive tool with an output schema and full annotation coverage, the description supplies the slug-reuse behavior, eligibility boundaries, and ownership requirement. Nothing needed 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?

Schema coverage is 100% and the parameter description already covers the slug/id format and the draft/needs-changes constraint, so the baseline is 3. The description adds a bit of value by reinforcing the slug-reuse consequence and eligibility constraint, though it does not introduce new syntax beyond the schema.

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

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

States a specific verb (Discard/soft-delete) and resource (your own draft listing), and explicitly distinguishes the scope from published/in-review agents. Names sibling tools (findagent_rollback_version / findagent_bump_version) as the alternatives for live agents, making it unambiguous relative to the crowded sibling list.

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

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

Explicit when-to-use (a draft you never submitted, or one sent back for changes) and when-not-to-use (published or in-review agents are NOT deletable here), with the correct alternative named. Eligibility is fully spelled out, leaving nothing to inference.

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

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

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

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

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

Three dense sentences with no redundancy. The deletion scope is front-loaded, followed by authorization, side effects on attached agents, and irreversibility. Every sentence earns its place.

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

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

For a single-parameter destructive operation with an output schema, the description fully covers what is deleted, who is allowed to delete, the consequence for attached agents, and the fact that it cannot be undone. No essential invocation information is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two sentences with no filler: the first states the action and the required parameter source, and the second tightens the scope with a clear 'only that one binding' qualifier plus the ownership gate. Every word earns its place.

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

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

For a single-required-parameter tool with an output schema and full schema documentation, this description is complete. It tells the agent what resource to target, where to get the ID, what will and will not be affected, and the authorization requirement—there is no meaningful gap.

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

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

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

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

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

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

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

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

The description tells the agent to supply attachment_id from findagent_list_kb_attachments, providing the correct source for the required parameter. It also gives scope guidance by explicitly stating what is not affected, but it does not name alternative sibling tools or list explicit when-not conditions, so it falls just short of a 5.

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

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

Annotations already provide idempotentHint and readOnlyHint, and the description adds meaningful behavioral context: it drops the stored connection, best-effort revokes the GitHub-side grant, and returns disconnected:true even when nothing was connected. This fully explains the operation's side effects and edge case behavior.

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

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

Three tightly written sentences: the core action, the behavioral notes, and the follow-up step. No filler or redundant restatement of the title.

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

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

For a zero-parameter action with an output schema, the description covers the operation's effect, idempotency, return behavior, and next step. Nothing an agent needs to invoke it correctly is missing.

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

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

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

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

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

The description states a specific action ('Disconnect / switch GitHub account') and resource ('stored GitHub connection'), clearly distinguishing it from findagent_connect_github. It also explains the purpose of disconnecting so a different GitHub account can be authorized.

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

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

The description gives explicit sequencing: after disconnecting, call findagent_connect_github to connect the new account. It also clarifies the idempotent nature, so the agent knows it is safe to call even when nothing is connected.

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

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

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

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

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

The description is concise: three sentences with no wasted words. It front-loads the core purpose, states the read-only nature, explains the payout exclusion, and provides the currency-unit detail. Every sentence earns its place.

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

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

For a zero-parameter tool with an output schema, the description is complete: it identifies exactly what data the agent will receive, the read-only safety profile, the payout exclusion, and the unit convention. There are no missing behavioral or usage details needed to call this tool correctly.

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

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

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

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

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

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

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

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

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

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds substantial unstated behavior: report_instructions is prepended to every member's/orchestrator's prompt and templated results, empty strings clear fields, saves are rejected on injection/secret scans, and archived departments are restored as drafts. 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 opening sentence names the operation and fields, and subsequent sentences add high-value caveats (no composition changes, restore flow, permission boundary, security check) without redundancy. Dense but appropriately sized for a tool with this many behavioral details.

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

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

For a mutation tool with 5 params, permissions, restore semantics, security checks, and an output schema, the description covers all necessary call-time knowledge: scope of edits, permission model, field semantics, restoration workflow, and where to get department slugs. The output schema covers return-shape needs, so 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 already covers all five parameters at 100% coverage, so the baseline is 3, but the description goes beyond: it explains the operational meaning of report_instructions, the clearing semantics of empty strings, the 'send status alone' restore rule, and the source of valid department slugs. This materially helps an agent choose and format values.

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 precise verb (Edit) and resource ('settings of YOUR OWN department'), enumerates the exact fields (reporting instructions, name, description), and explicitly separates itself from composition editing done in the web builder. This differentiates it from sibling edit tools such as edit_metadata and edit_price.

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 conditions: personal departments owned by caller, org departments restricted to owner/admin; explains when not to use it (composition changes go to web builder) and directs users to list_my_agents to discover departments. It also prescribes the restore workflow (status alone first, then edit) rather than leaving sequencing ambiguous.

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

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

Goes well beyond the annotations: discloses that edits publish immediately without admin review, that the caller must own the agent, that existing buyers are unaffected, and that thumbnail/example_output are display-only artifacts (not a live run). This is rich behavioral context an agent cannot infer from readOnlyHint/idempotentHint 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?

Dense but front-loaded: the core purpose leads, followed by the scoping disclaimer and sibling routing. The long parenthetical enumerating re-versioning paths is justified because it prevents misrouting, though it is the one place the prose could be tightened.

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

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

For an 11-parameter mutation tool with full schema coverage and an output schema, the description supplies everything an agent needs: editable fields, ownership requirement, immediate-publish behavior, sibling routing for non-display changes, and slug lookup pointers. No material gaps.

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

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

Schema coverage is 100%, so the schema carries most parameter detail. The description still adds partial-update semantics ('pass only the fields you want to change') and cross-references the lookup tools for valid category/facet slugs, which the schema itself does not.

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 (Edit) and resource (DISPLAY metadata of YOUR OWN PUBLISHED agent), then enumerates exactly which fields are editable. It also names what the tool does NOT touch (tools/actions/credentials/prompts), which sharply distinguishes it from siblings like findagent_bump_version and findagent_repull.

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 use it (display-only edits, go live immediately without re-review) and when not to (behavioral changes must route through bump_version, repull, or reintrospect_mcp). Adds the owner-only constraint and routes the agent to findagent_list_categories for valid slugs.

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

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

Annotations already mark this as non-read-only and non-destructive, and the description adds materially: owner-gating, audit-log recording, non-retroactivity, and that existing buyers keep access. This goes beyond the structured fields and tells the agent exactly what side effects to expect.

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

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

Four sentences, each carrying a distinct constraint (ownership, price rules, non-retroactivity, validation path), with the main action front-loaded. No filler or repetition.

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

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

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

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

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

Input schema covers all three parameters with descriptions and enums, so the baseline is 3. The description reinforces the 50000-cent cap and 'ignored for free' behavior, but does not add meaning beyond what the schema already states.

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

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

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

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

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

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

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the anonymisation policy (names, links, hosts, repo paths, credentials, project name stripped), the 'stated/approved decisions only' rule, and named refusal codes (`not_settled`, `listing_identifies`). It also makes explicit that nothing is published, so the agent understands the state transition.

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

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

Front-loads the purpose and the anonymisation guarantee, then describes inputs and refusals. It is dense and every clause carries information, though the single packed paragraph is heavier than necessary and could be split for easier scanning.

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

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

For a mutation-style tool with an output schema already defined, it covers everything an agent needs: prerequisites (own project, settled decisions, attestation), side effects (draft only, no publication), follow-on steps, and refusal conditions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties `attestation: "own-work"` to a confirmation of publish rights, locates `project_id` on the project card, and imposes an extra constraint on the listing fields (they must not name anything the anonymiser would remove), which the schema does not state.

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

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

States a specific verb+resource+scope: turning one of the caller's OWN projects into a private recipe DRAFT. It also distinguishes itself from the publication tools by clarifying this only produces a draft, not a published listing.

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 strong context: it requires your own project, it only uses stated/approved decisions, and it names the follow-on tool (findagent_submit_for_review) plus the scan/human review that consume the draft. It does not, however, distinguish itself from sibling draft creators like findagent_create_draft or findagent_create_code_draft, so the agent must infer when to prefer this over them.

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/openWorldHint annotations: it discloses the is_mcp_server_listing omission semantics ('read absence as unknown, never false'), that paid agents hide tools/skills until purchase, that action is visible only to owners, and that http headers/auth_ref are withheld. These are exactly the gotchas 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?

Purpose and return shape are front-loaded, then caveats follow in dense but information-bearing sentences. It is long, but nearly every clause carries a distinct behavioral fact rather than padding.

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

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

For a read tool with an output schema present, the description need not explain return values yet still enumerates them and covers the ownership/auth/omission edge cases that the schema and annotations cannot express. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema, so the description adds no syntax or format detail. It only reiterates the source ('by slug'), matching the baseline for a schema-complete parameter.

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

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

States a specific verb and resource ('Get the full store view of ONE published FindAgent marketplace agent by slug') and grounds it with an analogy to the website's agent detail page, cleanly separating it from the list-oriented sibling findagent_browse_agents.

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 handles the failure path (unknown/unpublished slug returns a needs_input result pointing back to findagent_browse_agents), which routes the agent correctly. It does not compare itself against siblings like list_my_agents or load_listing_tools, so it stops short of full 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 declare readOnly/idempotent/non-destructive and the description's 'READ-ONLY' is consistent, not redundant filler. It goes well beyond the annotations by disclosing ownership-conditional behavior (config health only for departments you own), the not-found collapse, and precisely what the health check reports (dropped/refused members, deliberately omitted package parts).

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

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

A single dense paragraph, front-loaded with what is read and followed by access and failure semantics. Every clause carries information, though the long em-dash-heavy middle sentence is harder to parse than it needs to be.

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

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

An output schema exists, so return-shape explanation is optional, yet the description still covers scope, ownership gating, failure modes, and the optional expensive sub-operation. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains what config health is for ('fix it before connecting') and that it is the slower part of the call because it reads each member agent, which justifies the default-true-for-owners behavior.

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

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

States a specific verb+resource ('Read one department you can access') and enumerates exactly what is returned: members with alias/role/agent slug, topology, report_instructions, MCP connect address, plus ownership-gated config health. An agent can distinguish this from findagent_list_departments or findagent_get_org without opening a schema.

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

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

Clearly scopes the reachable set (personal departments you own, org departments of orgs you belong to) and pins failure semantics (inaccessible, archived, and unknown slug all collapse to the same not-found). It never explicitly names findagent_list_departments as the discovery alternative in prose, but the access boundaries give strong usage context.

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 openWorldHint=true; the description goes further by confirming nothing is persisted or executed and explaining that private repos are handled server-side with the stored GitHub token so the AI client never needs repo access. This adds important security and privacy context beyond the annotations.

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

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

The description is front-loaded with the core action and return value, then moves to workflow and behavioral details. It is dense but every clause earns its place, covering purpose, return shape, follow-on tools, read-only behavior, and private-repo handling. It could be slightly tighter, but it is not bloated.

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

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

With an output schema present, the description correctly focuses on purpose, workflow, and behavioral constraints rather than return format. Annotations cover read-only and open-world hints, the schema fully documents parameters, and the description supplies the missing contextual details: private-repo support, server-side token handling, and the intended downstream workflow. 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 input schema has 100% description coverage for both parameters (repo and ref), so the schema already documents their semantics. The description repeats that the repo must be readable by the connected token and that private repos work server-side, which mirrors schema text rather than adding new parameter detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Pull the CALLER'S OWN GitHub repo (via their connected token)'. It clarifies scope, including that it works for private repos, and distinguishes itself from generic listing by framing the pull as the caller's own token-connected repo. The agent knows exactly what this tool returns: deterministic grounding plus a field contract.

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 next steps: use the grounding as the basis, then run findagent_submission_wizard, and finalize with findagent_create_draft. It also clarifies that the caller's own model does the synthesis (no FindAgent LLM cost) and that the tool is read-only, which sets expectations for when this is the right first step. No alternative tools are explicitly excluded, but the workflow routing is clear.

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

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

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

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

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

Two crisp sentences that front-load the main action, include the permission constraint and return behavior, and clarify edge cases. No wasted words; every clause adds value.

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

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

Given the tool's moderate complexity, the description covers all critical aspects: what it does, who can use it, what it returns (accept_url), the email-binding requirement, and the role options. The output schema exists, so return details are handled there. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter (email, role, slug, org_id) with clear explanations. The description repeats some of this (e.g., role default, ownership separate) but adds no new parameter-level information beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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

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

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

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

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

The description includes a permission prerequisite (owner/admin only) and states that ownership is transferred separately and never invited, which implies using a different tool for ownership changes. However, it doesn't explicitly name the alternative tool, though the sibling list contains findagent_transfer_org_ownership. It's clear enough for an agent to infer when to use this tool vs alternatives.

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

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

Annotations mark readOnlyHint=false, which already flags mutation. The description adds meaningful behavioral context: it removes only the caller's membership and enforces a last-owner constraint. It does not fully discuss reversibility, but for a simple leave operation with output schema present, this is solid.

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

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

Two sentences, no filler. The main behavior is front-loaded, and the important exception/alternative is stated immediately after. Every sentence earns its place.

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

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

For a simple two-optional-parameter tool with an output schema, the description covers the key facts: scope of effect, owner exception, and routing to the transfer tool. Nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is 100%, and both slug and org_id parameters are already described in the input schema. The tool description adds no parameter-specific guidance beyond what the schema provides, so the baseline 3 score applies.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a zero-parameter read-only list tool with an output schema, the description is complete: it explains what will be returned, when to call it, and how to interpret the result for the downstream create_draft flow. There are no apparent missing details an agent would need to invoke this tool correctly.

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful scoping behavior: only owned departments, extra admin-shared testing departments listed apart, and archived departments omitted. Some details, such as returned fields and 'READ-ONLY,' are redundant with the output schema and 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 front-loaded with the key scope and purpose, and most sentences earn their place by clarifying ownership, admin behavior, archival exclusion, and slug discovery. However, the sentence listing return fields is partly redundant given the output schema, and 'READ-ONLY' repeats an annotation.

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 and rich annotations, the description is complete enough. It covers scope, admin-specific visibility, archival behavior, and the reason an agent should call it.

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

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

The tool has zero parameters, so the baseline is 4. The schema is empty and fully described by having no inputs; the description appropriately does not invent parameter semantics.

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

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

The description states a specific verb (List) and resource (departments YOU own), defines what a department is, and distinguishes owned departments from shared admin-owned ones. It also explains the practical purpose: finding the slug required by other department 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 call this tool to find the slug the other department tools take and notes archived departments are excluded with a restore path via findagent_edit_department. It does not explicitly contrast with findagent_get_department or state when not to use this list tool.

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

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

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

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

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

A single dense paragraph with zero filler, and the most decision-relevant facts (permission scope, expired-invite inclusion) are front-loaded. It is packed but no sentence is wasted.

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

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

With an output schema present, return format needn't be re-explained, and the description fully covers permissions, the expired-invite edge case, and the token-security caveat. Nothing needed to call it correctly is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two sentences carry the entire message: the first states the operation and output shape, the second links the output to the relevant sibling. There is no filler or repetition of schema fields.

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

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

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

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

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

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

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

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

The description opens with a specific verb ('List') and a precise resource ('where a knowledge base you own is attached'), then names the three attachment targets (agent / department / personal) and what each row contains (attachment id, mode). This differentiates it from sibling tools like findagent_attach_kb and findagent_detach_kb without needing their schemas.

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

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

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

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

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

Annotations already mark readOnlyHint true; the description reinforces that with READ-ONLY and adds meaningful context about ingest lifecycle ('parsing'/'embedding' in flight, 'ready' searchable, 'failed' with error) and the ownership constraint. No contradiction with annotations.

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

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

Three tight sentences: purpose and statuses are front-loaded, downstream usage is one actionable clause, and the read-only flag is a deliberate final signal. Every sentence earns its place without redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A single front-loaded sentence states the action, scope, and returned fields with no filler. The 'READ-ONLY' flag is appended as a clear safety signal, and every clause earns its place.

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

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

For a parameterless read-only list operation with an output schema available, the description covers everything needed: what is listed, whose KBs are included, and what attributes are returned. There are no parameters to document and no hidden invocation requirements to infer.

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

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

The tool has zero parameters, so the baseline is 4; there is nothing for the description to add about argument semantics. The schema already records an empty parameter set with 100% coverage.

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

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

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

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

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

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

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

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

Annotations already supply readOnlyHint=true; the description adds useful context beyond that by noting that active membership is the access requirement, and that org identification can be via org_id or slug. This goes beyond the structured annotation without contradicting it.

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

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

Three short sentences carry all essential information with no filler. The primary action and returned fields are front-loaded, with access and identification details placed afterward.

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

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

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

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

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

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

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

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

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

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

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

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

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