Apologetics Wiki

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely usable behavioral context: which editions are always present versus the NWT line being conditional on the verse already being quoted on a site article, meaning output composition varies by verse. The unexplained '[no key]' token detracts from otherwise solid 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 text front-loads a list of translation names rather than the tool's purpose, and devotes its length to output composition that the output schema could carry. The trailing '[no key]' fragment is pure noise that consumes attention without conveying anything actionable.

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?

Because an output schema exists, the description needn't document return values, and yet that is almost all it does. The essential facts an agent needs - the action performed and the expected format of 'reference' - are absent, leaving the definition incomplete for its actual invocation surface.

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

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

Schema description coverage is 0% and the sole parameter 'reference' (a string, 1-120 chars) is never mentioned in the description. No format or example is supplied (e.g., 'John 3:16'), so an agent gains no meaning beyond the raw schema constraint, and with a low-coverage single mutation-free parameter the description is expected to compensate but 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?

The description enumerates the translation lines that appear in the output (KJV, Young's Literal, JPS 1917, original-language gloss), which implicitly signals a side-by-side comparison, but it never states the action verb or what the tool actually does with the input. An agent must infer 'compares translations of a Bible verse' solely from the name and the list of editions, and the stray '[no key]' fragment further muddies intent.

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

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

There is no when-to-use guidance and no differentiation from the closest sibling, get_bible_passage (or get_verse, lookup_quote, get_cross_references), which likely also return scriptural text. Nothing tells the agent whether to pick this tool over a plain passage lookup.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent). The description adds genuinely useful behavior: the returned key 'is shown once,' warning the agent it is non-retrievable, plus the scope choices and a '[no key]' note implying this call needs no prior auth. It stops short of noting code expiry or rate limits.

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

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

Four short, front-loaded fragments with no filler — the core action leads. The bracketed '[no key]' is terse to the point of ambiguity, which slightly hurts clarity.

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 auth tool with no output schema, the description covers the essential mechanics: input (emailed code), the returned secret, its one-time visibility, and scope options. It could say more about what the response contains or code lifetime, but it is largely sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'emailed code' = otp and lists the scope values, but 'email' is left unmentioned and no format or length guidance is given. Partial compensation, so a middling score.

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: 'Exchange the emailed code for a scoped API key.' This precisely describes the operation and, via 'emailed code,' implicitly ties it to the request_sign_in sibling, so an agent can distinguish it from other 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?

Usage is only implied — the phrase 'emailed code' suggests this follows request_sign_in, but the description never explicitly names that prerequisite or states when not to use it. There is no explicit alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: that bible/Apocrypha passages for books with a background essay include the essay's URL, and Apocrypha/Non-Canonical passages include the canon note. The '[no key]' marker hints at no authentication, but return shape and any rate/limit behavior are unstated.

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

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

Short and front-loaded: the core 'fetch by id with these prefixes' leads, followed by the conditional content behaviors. Sentences are terse and mostly earn their place; the bracketed '[no key]' is slightly cryptic but compact.

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

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

With no output schema, the description carries the burden of describing returns. It does disclose two conditional output behaviors (essay URL, canon note), but never describes the general return shape for the other ID namespaces, leaving the generic-fetch contract partially unspecified. Adequate but with a clear gap for a tool spanning five resource types.

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

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

Schema description coverage is 0% and the single 'id' param has no schema-level documentation, so the description must carry the load. It does this well by specifying the required prefix schemes that give the id its structure. It does not cover the min/max length constraints or format nuances, so the compensation is partial.

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

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

States a specific action (fetch by id) and enumerates the accepted ID namespaces (article:, hub:, bible:, apocrypha:, non-canonical:), which lets an agent recognize it as a generic dispatcher rather than a type-specific getter. The verb 'fetch' is generic and overlaps with the name, but the prefix list adds real discriminating content. It stops short of explicitly naming siblings like get_article or get_bible_passage.

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 ID prefix list implies which resource types are valid targets, giving implicit guidance about when the tool applies. However, it never states when to prefer fetch over the many type-specific siblings (get_article, get_bible_passage, get_verse) or states any exclusion. Usage must be inferred from the accepted prefixes.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description's remaining content mostly previews return values, which the output schema already documents, so genuinely new behavioral context is thin (no auth, rate-limit, or matching-quality notes).

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

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

Two compact, front-loaded sentences with no padding. The trailing '[no key]' artifact is unexplained and slightly muddies an otherwise clean statement.

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

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

For a simple two-parameter, non-nested lookup with an output schema, the description conveys purpose and result content adequately. It falls short only on parameter semantics (limit) and on any hint of match quality or fallback when nothing matches.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only implies that the input is 'an objection' text. The 'limit' parameter is never mentioned, and there is no guidance on the 500-character cap or what the integer bound controls.

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: matching an objection to common arguments and published articles, then returning the claim, answer, points, and URLs. This distinguishes it reasonably well from siblings like search_articles or related_articles, though it never names an alternative to sharpen the distinction.

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

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

The phrase 'Match an objection' implies the usage context (you have a claim/objection and want supporting material), but there is no explicit when-to-use, when-not-to-use, or routing to sibling tools such as search_articles or get_common_argument. Usage 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real context beyond them: the default returns a summary, full=true returns the body but is 'still capped' (a truncation disclosure), and '[no key]' signals no authentication is required. It stops short of quantifying the cap or describing the return shape.

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

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

Three short, front-loaded sentences with no filler; the identifier forms come first and the default/full behavior second. The telegraphic style and the bare '[no key]' tag are terse to the point of being slightly cryptic, but nothing is wasted.

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

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

For a 3-parameter read tool with no output schema, the description covers the essentials but leaves gaps an agent would want: what 'capped' means numerically, how identifier precedence resolves, and behavior when no parameter is passed. Adequate but not complete.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely does: it defines what path, slug, and full mean, and implies path/slug/URL are alternative identifier forms. It omits precedence when multiple identifiers are supplied and does not explain the zero-required-parameter case (what happens if none is given).

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

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

The description names a specific resource (a published article) and the three accepted identifiers (path, slug, or full URL), plus the default/full output distinction. The scope word 'Published' usefully excludes drafts. However, it does not distinguish itself from the sibling get_article_summary or get_article_section, which is confusing given its own default already returns a summary.

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

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

It tells the agent the default is a summary and to set full=true for the body, which is useful intra-tool guidance. It gives no when-to-use versus get_article_summary, get_article_section, or related_articles, and no note on which identifier to prefer when several could apply.

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

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

Annotations already declare the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds one genuinely useful behavioral fact — the section is "capped in length" — but never states the cap value and leaves "[no key]" unexplained. It adds some value but not rich behavioral 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 definition is short and front-loads the resource being fetched, which is good. However, the cryptic "[no key]" fragment is trailing text that wastes space and confuses rather than informs. Efficient overall but not cleanly structured.

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 annotations cover the read-only safety profile. The description appropriately notes truncation via "capped in length". It still leaves parameter usage and when-to-use guidance unaddressed for a three-parameter tool, so it is only minimally complete.

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

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

Schema description coverage is 0%, so the description carries the full burden. It only loosely maps to the required 'heading' parameter ("one heading's section") and says nothing about 'path' or 'slug', their relationship, or which identifies the article. With two of three parameters entirely undocumented in both schema and description, it does not compensate for the coverage gap.

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

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

The description states a specific resource (a single heading's section from a published article) and a distinguishing scope versus get_article and get_article_summary. The trailing "[no key]" fragment is cryptic and does not help an agent identify the tool. Purpose is clear enough to select the tool over 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?

There is no when-to-use guidance, no when-not-to-use, and no named alternatives. An agent must infer that this is for fetching one section versus whole-article tools like get_article without any stated condition. This is bare statement of function with no usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds only '[no key]', a small piece of extra context, and nothing about rate limits or behavior 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?

Two compact sentences that front-load the return content, followed by the input hint. The trailing '[no key]' is cryptic and slightly unpolished, but overall the text is efficient with little waste.

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

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

An output schema exists, so return values need not be explained in detail. The description covers the purpose and input format adequately, though the sibling-selection gap keeps it from being fully complete for a tool with several near-neighbors.

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

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

Schema coverage is 0%, so the description must carry the load. It does tell the agent how to pass a slug, a path, or a full URL, which compensates partially, but it does not distinguish the two separate 'path' and 'slug' properties or clarify when to use each.

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 and enumerates the returned fields (title, description, key points, canonical URL) for one article. It is clear what it does, but it does not differentiate from sibling read tools like get_article or get_article_section.

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 parameter-passing guidance ('Pass a slug, a path, or a full https://apologetics.wiki URL') but no when-to-use vs alternatives guidance. With get_article and get_article_section in the sibling set, the agent has to infer which one to pick.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real value beyond them: canon_status and disclaimer_url on apocryphal results, a background URL when a book has an essay, and specific edition resolutions. '[no key]' also signals no auth requirement. It stops short of describing result shape or size.

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

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

Core purpose is front-loaded, which is good, but the alias list is long and partly redundant (1 Enoch/Enoch/Book of Enoch; 3 Enoch/Hebrew Enoch; Jubilees/Jub/Little Genesis). The enumeration is defensible for input correctness but consumes most of the text and pushes parameter explanation out entirely.

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

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

For a read-only lookup with no output schema, the description does cover what comes back (verse text, canon_status, disclaimer_url, background URL) and the special edition resolutions. It is still incomplete on how verse/chapter/reference interact, but the essential return behavior is addressed.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning, yet it only explains 'book' (accepts book names or OSIS codes, with examples). Verse, chapter, and reference are essentially undocumented — chapter is only hinted at via 'a whole chapter returns the verse text', and reference (which looks like a combined reference string) is never clarified.

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: returns King James text for a book name or OSIS code, and clarifies scope (a whole chapter returns verse text, Apocrypha and Non-Canonical included). An agent can tell what it fetches. However, it never distinguishes itself from siblings like get_verse or compare_translations, so it falls short of a 5.

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

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

No explicit when-to-use or when-to-use-something-else guidance, and no sibling alternatives are named. The alias-resolution rules (John, jhn, 1 Enoch, Jub, etc.) imply which inputs are valid but that is content explanation rather than selection guidance, leaving usage only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so the safety profile is covered structurally. The description adds one genuinely new behavioral fact — '[no key]', implying no authentication is required — plus the note that a site canon note is included. It says nothing about error behavior for unrecognized books, but with annotations carrying the safety burden a 3 is fair.

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 tight sentence with the most decision-relevant information (which traditions) front-loaded and no filler. The trailing '[no key]' fragment is terse to the point of ambiguity, which is the only structural blemish.

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 no explanation, and annotations cover the safety semantics. For a single-parameter lookup the description is nearly sufficient; the remaining gap is the input format for the book argument.

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?

One parameter with 0% schema description coverage, so the description must compensate and only partially does: 'Bible, Apocrypha, or Non-Canonical book' constrains the domain of the book argument but never states the accepted format (full name, abbreviation, or identifier). Minimal compensation, so a 3.

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

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

States a specific verb (get) and resource (canon status), and enumerates the four traditions whose status is returned (Protestant, Catholic, Orthodox, Ethiopian), so the agent knows exactly what comes back. No sibling tool covers canon status, so it is trivially distinguishable from the list.

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

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

The description never says when to reach for this tool instead of siblings like get_verse or get_bible_passage, nor what prerequisites exist. The only guidance-like element is the cryptic '[no key]' fragment, which is not a usage rule. Usage is at best inferred from the purpose.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds only that returned URLs are absolute, plus an unexplained '[no key]' fragment whose meaning is unclear; it does not disclose whether both identifier params are needed or how multiple citations are ordered.

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 statement is short and front-loaded, but the dangling '[no key]' fragment is cryptic noise that adds no actionable meaning and slightly muddies the 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?

An output schema exists, so return values need not be explained, but with both parameters undocumented and no guidance on path-vs-slug selection, the definition leaves the agent unable to confidently construct a call.

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

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

Schema description coverage is 0% and the description says nothing about 'path' or 'slug' — it never clarifies whether they are alternatives, whether one is required, or what format each takes. With two undocumented identifier parameters, the description fails to compensate for the schema gap.

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

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

The phrase 'The sources listed on one article, with absolute URLs' identifies the resource (citations for a single article) and the return shape, but there is no verb and no differentiation from siblings like get_article or related_articles. An agent can guess the intent, but it isn't stated as an action.

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

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

There is no indication of when to call this versus get_article, fetch, or lookup_quote, and no prerequisites or alternatives are named. The agent must infer usage purely from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds value by listing what the response contains (answer, texts, anchor, article URL), which matters since there is no output schema, but the trailing 'or Article coming' and '[no key]' are unclear and undercut the 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?

It is short and front-loads the resource, but the sentence is awkwardly constructed and the fragment '[no key]' and unfinished 'Article coming' reduce clarity rather than adding 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 no output schema and no annotations covering return content, the description is the sole source for what the agent gets back; it gestures at the fields but leaves the article-URL/Article distinction and '[no key]' unexplained. For a lookup tool with an undocumented parameter, this is not complete enough.

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

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

Schema description coverage is 0% for the single id parameter, so the description must carry the meaning. 'One claim by id' does indicate that id identifies a claim, but adds no format, source, or constraint detail beyond that bare hint.

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 conveys that this returns a single claim/argument by id and enumerates its payload (answer, texts, group-page anchor, article URL), which distinguishes it implicitly from the plural sibling list_common_arguments. However, the phrasing is garbled and no explicit verb or sibling differentiation is stated, leaving the purpose only inferable.

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

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

There is no statement of when to use this tool versus list_common_arguments, find_articles_for_claim, or any other retrieval sibling. The only hint is the singular 'one claim by id', which implies a lookup-by-id use case but names no conditions or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the result is a single graph file ('One graph file'), which is a modest hint about response shape but nothing about size limits, retries, or auth.

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

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

It is short, but the telegraphic fragments ('Nodes and edges for the connection map.', '[no key]') are under-specified rather than concise. The bracket note '[no key]' is cryptic and unhooked from any behavior, and the param facts are listed rather than front-loaded with purpose.

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?

Return values are covered by the output schema, so that need not be explained. However, with three enum parameters at 0% schema coverage, the description leaves 'type' undocumented, provides no usage context versus four sibling graph/connection tools, and adds ambiguous output-side terms ('from', 'to') that look like missing parameters.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It explains 'level' (book or chapter) and 'testament_filter' (all, ot, nt), but completely omits the 'type' parameter (quotes, fulfilled, alludes, see-also) and instead describes 'from'/'to' — fields that are not parameters in the schema, which risks confusing the caller.

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 the returned resource ('nodes and edges for the connection map') but uses no verb and never explains what a 'connection map' is. It does not distinguish this tool from close siblings like get_connections_by_book or get_connection_stats, so an agent cannot tell which to pick from the text alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_connections_by_book or get_connection_stats. The fragments '[no key]' and 'One graph file' hint at behavior but do not tell the agent when this tool is the right choice.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real semantics for min_weight (drops thinner chapter links and re-totals what remains), which the annotations cannot express. However 'One summary file' and '[no key]' are cryptic and unexplained, leaving behavioral gaps.

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?

Sentences are short and the resource/scope is front-loaded, so it reads quickly. But 'One summary file. [no key]' are unexplained fragments that consume space without conveying actionable meaning.

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

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

An output schema exists, so return-shape details are not required. Still, for a 3-parameter tool with 0% schema coverage, the description leaves the required book parameter and the cryptic trailing notes underspecified relative to the tool's complexity.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the type enum options and the effect of min_weight, which is genuine added value, but the required 'book' parameter (format, KJV naming expectations) is never addressed beyond 'one King James book', and 'adds up what remains' is vague about the aggregation result.

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

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

States a clear verb+resource: returns Old Testament and New Testament connections for a single King James Version book. The scope ('one book') implicitly separates it from siblings like get_connection_graph and get_connection_stats, though it never names an alternative explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance and no routing to alternatives such as get_cross_references, get_connection_graph, or get_connection_stats. The reader has to infer the use case entirely from the resource name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds genuinely extra behavioral context: 'One summary file' signals a single non-paginated response, and '[no key]' signals no authentication is required.

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

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

Two short fragments with no filler, and the payload contents are front-loaded before the 'one summary file' scope note. It is dense to the point of being slightly cryptic ('arc counts', 'See Also cap') but nothing is wasted.

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

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

With an output schema present, the description need not restate return values, and it appropriately covers what the tool provides plus the no-key/single-file behavior. For a zero-parameter read-only tool this is nearly complete; only the absence of any usage context keeps it from a 5.

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, which is the baseline-4 case per the rubric, and the description correctly implies a no-argument call. There are no parameter nuances to explain, so no additional credit is warranted or available.

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 concretely enumerates what the tool returns (row counts, arc counts, the See Also cap, licenses, download URLs) for the connection files, which pins down the resource as a metadata/stats summary. It is clear but offers no differentiation from siblings like get_connection_graph or get_connections_by_book, so it lands at 4 rather than 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only hint is the implicit sense that this is a stats/metadata lookup, which is not enough to route an agent among ~35 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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds one genuine behavioral detail — results are 'curated' and scoped to the 66-book canon — which is useful. The trailing '[no key]' is uninterpretable and adds no clarity.

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

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

Two short sentences are reasonably front-loaded, but the inline Bible-reference example and the stray '[no key]' fragment are noise that distracts rather than informs. Length itself is fine; the content is not fully earned.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description still omits parameter format guidance and sibling differentiation, leaving gaps an agent would need in order to invoke it confidently.

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

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

Schema description coverage is 0% for the single required 'reference' parameter, so the description must carry the burden and does not. It only implies 'for a passage' without giving the expected format (e.g., 'John 3:16'), length constraints, or accepted book naming.

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 the tool returns curated cross-reference links and OT/NT connections for a passage, which is understandable. However, it does not distinguish itself from closely related siblings like get_connections_by_book, get_connection_graph, and get_citations. The Jude 1:14–15 / 1 Enoch 1:9 example followed by '66 books only' is confusing rather than clarifying.

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

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

There is no statement of when to use this tool versus the connection- or citation-oriented siblings, and no prerequisites or exclusion conditions are given. The agent is left to infer usage entirely.

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, non-destructive and closed-world, so the safety profile is covered. The description adds useful behavior (case-insensitive substring match, zero-count on no match), but the cryptic fragments 'One summary file' and '[no key]' add little interpretable 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?

It is short and front-loads the resource, but the telegraphic sentence fragments ('One summary file. [no key]') do not clearly earn their place and read as unexplained notes rather than useful structure.

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

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

An output schema exists, so return values need not be explained, and the read-only profile is fully annotated. Still, the ambiguous fragments about 'one summary file' and '[no key]' leave the agent guessing about output granularity and prerequisites.

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

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

Schema coverage is 0% and the lone 'theme' param has no schema description, so the description must carry the load. It does clarify that theme is a case-insensitive substring match, which is real added meaning, but leaves length limits and matching target implicit.

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 identifies a specific resource ('Messianic rows from the connection files') and an implicit retrieve operation, so an agent can tell what data comes back. However, it makes no attempt to differentiate itself from related siblings like get_connections_by_book or get_connection_stats that also source from connection data.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives. The only clues are behavioral ('theme is a case-insensitive substring'), which imply filtering rather than directing the agent among tools.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the bar is lower. The description adds real context beyond them: which include values are available, that Apocrypha/Non-Canonical results return canon_status and disclaimer_url, and that no key is required.

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

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

Four dense sentences, each front-loading a distinct fact (scope, default output, include options, shelf-specific fields) with no wasted words.

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

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

An output schema exists, so return details need not be explained. The description covers scope, include behavior, and shelf-specific outputs, but leaves the required reference format and sibling differentiation unaddressed.

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

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

Schema coverage is 0%, so the description must compensate. It enumerates the include options (greek, hebrew, parallels, study_links, cross_refs, connections) matching the enum, but never explains the reference string format, which is the core required 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 clear verb+resource ('King James text for a free-form reference') and scopes it across the Bible, Apocrypha, and Non-Canonical shelves. However, it never distinguishes itself from the sibling get_bible_passage, which an agent would need to choose between.

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 phrase 'free-form reference' implies this tool accepts flexible input where a structured-passage tool would not, hinting at when to prefer it. But there is no explicit when-to-use, when-not, or named alternative, so the agent must infer the distinction from get_bible_passage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-annotation context in "[no key]" (no authentication required) and in identifying which backend indexes are queried. It says nothing about behavior when the identifier is not found, or about precedence when both identifiers are supplied, which is a real gap for a lookup 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 short fragments, front-loaded with what the tool returns and followed by how to address it. Nothing is padded. The bracketed "[no key]" is terse to the point of being cryptic, which keeps it from a 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?

With no output schema, the description must explain what "word-page data" actually contains, and it doesn't — an agent cannot tell whether it gets definitions, lexicon entries, occurrences, or references. For a two-parameter lookup tool the addressing instructions are adequate, but the return shape and the search-vs-fetch boundary from search_word_study remain unexplained.

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

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

Schema description coverage is 0% and both parameters are undocumented in the schema, so the description carries the burden. It does state that both parameters are identifiers (a slug or a Strong's number), which is the essential semantics, but it gives no format examples (e.g. "G26"/"H430"), no indication of precedence if both are passed, and doesn't clarify that neither is required. Partial compensation only.

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?

It names a specific resource (Greek or Hebrew word-page data) and its source indexes, which is enough for an agent to know it fetches a word-study entry rather than a verse or article. It does not, however, distinguish itself from the sibling search_word_study, so the agent must infer the boundary. Clear verb+resource, but no sibling differentiation.

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

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

"Pass a slug or a Strong's number" is parameter instruction, not tool-selection guidance. There is no statement of when to use this instead of search_word_study or get_bible_passage, and no exclusions or prerequisite conditions. The agent is left to guess the retrieval-vs-search boundary.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met. Beyond that, the description discloses two non-obvious behaviors: shelf names are case-insensitive, and an unknown shelf returns the valid shelf list rather than an error — real error-path context an agent needs.

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

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

Short, front-loaded sentences that each add a distinct fact (scope, case sensitivity, pagination, error fallback) with no padding. The trailing '[no key]' fragment is cryptic and slightly undercuts the otherwise clean structure.

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

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

For a 3-param listing tool with no output schema, the agent still lacks any hint of the return shape (item fields, ordering, page size defaults) and the meaning of 'limit'. The shelf and cursor behavior is covered, but the definition is not quite complete.

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

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

Schema description coverage is 0%, so the description must carry the load. It usefully documents 'shelf' (case-insensitive, optional) and 'cursor' (from previous page), but says nothing about 'limit' or its 1-100 bound, leaving one of three parameters undocumented.

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

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

States a specific verb and resource ('List published articles') plus the optional scope ('on one shelf'), so the agent knows it enumerates rather than searches. It does not explicitly differentiate itself from close siblings like search_articles or related_articles, which keeps it from a 5.

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

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

Gives implied usage guidance via pagination ('Pass cursor from the previous page') and the optional shelf filter, which tells the agent how to browse incrementally. However, it never states when to prefer this over search_articles or find_articles_for_claim, leaving the routing decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful context ('[no key]') and enumerates returned fields, which compensates for the absent output schema. It does not cover pagination semantics or result limits in depth.

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

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

The description is compact and front-loads the content shape, but the awkward 'or Article coming' phrasing and the bracketed '[no key]' token reduce clarity. It is reasonably sized but not cleanly structured.

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

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

With no output schema and 0% schema description coverage, the description does well to enumerate return fields and name three of four parameters. It still omits the limit parameter and paging behavior details, so it is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains group and query as filters and cursor for paging, which is helpful, but leaves the limit parameter entirely unaddressed and gives no format constraints for the others.

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 conveys that this returns recurring 'claims' and enumerates the returned fields (claim, one-line answer, texts, article URL). However, it never states the verb 'list' explicitly and the phrase 'or Article coming' is garbled, so the exact purpose is only inferable. It also doesn't clearly distinguish itself from the sibling get_common_argument.

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 says how to filter (group, query) and page (cursor) but gives no when-to-use guidance and no alternatives. There is no indication of when this list is preferable to get_common_argument or search.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the one piece of behavior annotations cannot express: the call requires an authenticated session. It stops short of noting pagination or result limits.

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

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

Two short fragments with no wasted words, and the resource is front-loaded ahead of the auth constraint. It reads slightly telegraphically, but nothing needs trimming.

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 tool with no output schema, the description covers the essential what and the auth prerequisite. Missing only return-shape/pagination detail, which is a minor gap given the tool's simplicity.

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 (schema coverage 100% on an empty object), so the baseline is 4. There is nothing for the description to clarify beyond the auth context it already 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 names the resource precisely (the signed-in account's saved articles and Bible verses), which is clear and specific. However, there is no explicit verb and no differentiation from siblings like list_shelves or list_articles, so an agent cannot tell from the text alone how this list differs from those other listing tools.

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

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

The bracket tag '[sign-in required]' signals a precondition, which is useful routing information toward the sibling auth tools (request_sign_in, confirm_sign_in). Beyond that, there is no guidance on when to prefer this tool over list_shelves or other listing 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful return-shape context (hub URLs and article counts) and the '[no key]' note, which is non-obvious. It says nothing about pagination or ordering, but with annotations this level of added context is a reasonable 3.

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

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

The description is a single efficient sentence, but it is a noun-fragment list rather than a front-loaded statement of purpose, and the trailing '[no key]' tag is unexplained boilerplate. It is short without being maximally useful.

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

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

With no output schema and no parameters, the description carries the burden of explaining what comes back; it names hub URLs and article counts, which is partly sufficient. It does not clarify the hierarchy of shelves or ordering, leaving some ambiguity for a zero-parameter tool an agent must call blind.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-related information is missing because no parameters exist.

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 enumerates the subject areas the shelves cover (religions, Islam branches, Bible, Apocrypha, Non-Canonical) plus the returned fields (hub URLs, article counts), which hints at a topical index. But it never states a verb or says it 'lists shelves', so the purpose must be inferred from the tool name. It does not distinguish itself from sibling listing tools like list_articles or list_common_arguments.

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

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

There is no statement of when to call this versus the many sibling list/search tools, and no prerequisites or exclusions. The only implicit cue is that it is a navigation/index tool, which an agent has to infer. An agent choosing among a dozen list_* and get_* siblings gets no routing help.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and openWorldHint=false, so the safety profile is handled. The description nonetheless adds two useful behavioral facts: results are constrained to the site's quote list (out-of-list references yield nothing), and the '[no key]' note signals no authentication. It does not, however, explain pagination, error behavior, or the shape of an empty result.

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

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

It is short and error-free, but the content is poorly front-loaded: the leading clause describes the returned object instead of the action, and the '[no key]' tag is appended awkwardly. Given an output schema already exists, this is the wrong information to spend words 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?

Because an output schema exists, the description need not explain return values, yet that is most of what it does. The genuinely missing piece – how to format the 'reference' argument and when to prefer this tool over get_verse or get_bible_passage – is absent, leaving the definition only partially complete for a lookup tool with an unannotated parameter.

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

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

The single parameter 'reference' has 0% schema description coverage, so the description carries the full burden of explaining it – yet it says nothing about format (e.g., surah:ayah, hadith collection:number) or valid values. With one undocumented required parameter, the description fails to compensate for the schema gap.

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

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

The description identifies the resource ('A Qur'an or hadith quotation stored on this site') but never states a verb for the action the tool performs – it reads as documentation of the return value rather than a lookup. An agent can infer it retrieves a quote by reference, but there is no differentiation from siblings like get_verse, get_bible_passage, or get_canon_status.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative among the many lookup siblings. The '[no key]' tag implies no authentication is required, which is mild usage context, but the description never explains when a caller should reach for lookup_quote instead of the other reference-lookup tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely useful context by flagging that authentication is required, but says nothing about return shape, ordering, or pagination.

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

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

Two tight clauses with zero waste; scope is front-loaded and the auth constraint is appended where it is immediately visible.

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

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

For a simple read tool the description covers scope and the auth precondition, and annotations cover safety. However, with no output schema and an undocumented filter parameter, an agent still cannot tell what a valid status value is or what the response will contain.

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

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

The single 'status' parameter has 0% schema description coverage, so the description carries the burden. Mentioning 'their review status' hints that status relates to review state, but it never explains accepted values, defaults, or whether omitting it returns all statuses.

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

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

Names the resource (the account's own suggestions) and adds the scope qualifier 'signed-in account's own' plus what it surfaces (review status). An agent can distinguish it from the write-side siblings suggest_article_change and suggest_topic, though the verb (list/retrieve) is only implied rather than stated.

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

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

The '[sign-in required]' tag gives a clear precondition, but there is no guidance on when to reach for this versus suggest_topic, suggest_article_change, or the list_* siblings, and no statement of whether the status filter is optional or how to use it.

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

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds real context: an automated spam/abuse/sourcing check runs before storage, failures are explained, passing articles land in a pending state, and trusted_author status does not bypass review. It does not describe the error shape or what an accepted submission returns.

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, purpose front-loaded, and each sentence adds a distinct fact (validation, storage state, author status). No filler.

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

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

For a write tool with no output schema and 0% parameter coverage, the workflow description is good but the description never compensates for the undocumented schema. An agent still has to guess what 'shelf' means, whether summary is required, or what an accepted proposal returns.

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?

Four required parameters (title, shelf, summary, markdown) and an optional sources array get no description text in either the schema (0% coverage) or the description. The description only alludes to 'sources', leaving shelf, summary, markdown formats undefined by any surface.

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 ('Propose a new article') and the payload it accepts ('with sources'). The word 'new' implicitly separates it from sibling suggest_article_change, though no sibling is named explicitly.

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

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

The description establishes prerequisites ('[sign-in required]') and describes the submission pipeline, but never states when to choose this over suggest_article_change or suggest_topic. Usage context is implied rather than 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?

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's only remaining job is to add behavioral context such as result ordering, default limit, or the relationship semantics. It adds nothing beyond restating the resource, and the trailing '[no key]' token is unexplained noise rather than 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 single sentence is short and front-loaded, but the orphaned '[no key]' fragment adds confusion without earning its place, and the sentence is a noun phrase rather than an actionable instruction.

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. But for a 3-parameter, all-optional tool with 0% schema coverage and no usage guidance, the description leaves key questions unanswered — the interplay of slug vs reference and the behavior when neither is provided.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It alludes to 'slug' and 'a scripture reference' (mapping loosely to the reference param) but never explains their format, whether they are mutually exclusive or combinable, or mentions the 'limit' parameter at all.

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

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

The description names the resource (articles) and the relationship that drives the result (share a shelf or a verse), which is more than a tautology. However, it is a bare noun phrase with no verb, so the agent must infer that the tool retrieves related articles, and it doesn't clearly distinguish this from graph-oriented siblings like get_connections_by_book or get_connection_graph.

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

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

There is no statement of when to use this tool versus get_article, search_articles, or list_articles. More critically, with zero required parameters, nothing tells the agent whether slug, reference, or both should be supplied, or what happens if neither is given.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description's contribution is the sign-in requirement and the single-item scope, both useful, but it doesn't say whether removal is reversible or what happens when the item isn't saved.

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 compact sentence plus a bracketed prerequisite tag, front-loaded with the action and target. No filler, though the bracketed tag reads as an afterthought rather than integrated 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?

For a two-parameter destructive mutation with full annotation coverage and no output schema, the essentials are mostly present. The gaps are the 'ref' format and non-existent behavior on an unsaved reference, which the description leaves unstated.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It partially covers 'kind' by naming 'article or Bible verse', but says nothing about the 'ref' parameter's expected format (an article identifier vs. a verse reference like 'John 3:16'), leaving a required 2-char-to-300-char string undocumented.

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

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

States a specific verb ('Remove') and resource ('one saved article or Bible verse') and scopes it to the signed-in account, which effectively contrasts it with save_item and list_saved. It stops short of naming a sibling explicitly, so an agent gets a clear purpose but no direct disambiguation.

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 '[sign-in required]' tag gives a prerequisite, and 'one saved article or Bible verse' implies it operates on items already saved (so save_item must have run first). There is no explicit when-to-use vs. when-not-to-use guidance or named alternative.

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

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

Goes well beyond the annotations by disclosing that no email is sent, that the link must be opened in a browser, that a human check gates the code email, and that a second tool call is required. Annotations only cover the safety profile (readOnly/idempotent/non-destructive).

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

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

Dense and front-loaded, leading with the primary action and then the workflow. The trailing bracketed '[no key]' is cryptic and unexplained, which slightly detracts.

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

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

For a no-output-schema tool, it explains the full two-step flow adequately. The main omission is clarifying the optional email parameter's role and what the link returns.

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 sole email parameter has 0% schema description coverage and is optional (required: []), yet the description never mentions it, its format, or whether it is needed. The description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Get the sign-in link') and immediately distinguishes this from its sibling confirm_sign_in by framing the two as a two-step flow. An agent can tell them apart without inspecting 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 describes the sequence: get the link, open it in a browser, then call confirm_sign_in with the emailed code. This gives clear workflow context, though it doesn't state when-not-to-use or what happens if the email parameter is omitted.

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 this is a non-read-only, non-destructive, non-idempotent write with no open-world access. The description adds the sign-in requirement, which the annotations do not cover, but it omits the behavior implied by idempotentHint=false, i.e. whether re-saving the same item duplicates or errors, and says nothing about confirmation or failure behavior.

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

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

It is a single tight sentence with the precondition appended, front-loading the action and resource with no filler. The brevity is appropriate to a two-parameter tool, though it is achieved partly by omitting detail rather than by disciplined editing.

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

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

There is no output schema, so return values need no explanation and the sign-in requirement is covered. Still, for a non-idempotent write tool the description never addresses duplicate saves, the meaning of ref, or what a successful save yields, leaving real gaps for an agent to guess at.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only partially does: matching "article path or a Bible verse path" against kind="article"/"verse" is suggestive, but the required ref parameter is never explained as a path format or with examples despite its 2-300 length bounds. Neither parameter's expected value syntax is clarified.

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 (save) plus the two resource types it accepts (article path, Bible verse path), scoped to the signed-in account. That verb makes it separable from list_saved and remove_saved, but no sibling is named explicitly, so it stays at a strong-but-not-exemplary 4.

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

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

The bracketed "[sign-in required]" tells the agent the session precondition for calling it, which is genuine usage context. However, it never says when to prefer save_item over siblings like list_saved, remove_saved, or suggest_topic, so the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds value by disclosing the result shape (id, title, url, text) in the absence of an output schema and by hinting at an auth/no-key requirement. It still omits pagination, result limits, rate limits, and what corpus is searched.

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?

Extremely short and front-loaded with no filler sentences. It is efficient, though the bracketed "[no key]" fragment is unpolished and unexplained, slightly undercutting the otherwise tight packaging.

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 search tool with no output schema, a 0%-documented parameter, and two sibling search tools, the definition omits the corpus searched, query format, result limits, and any routing guidance. The return-field note is a small bright spot, but the agent still cannot confidently decide when this tool is the right choice.

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

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

Schema description coverage is 0% for the single 'query' parameter, so the description carries the burden of explaining it and adds nothing at all — no hint about query syntax, natural-language vs keyword form, or handling of the 200-char cap. The parameter is nearly self-evident, but the definition does not compensate for the coverage gap as required.

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?

"Search" and "ChatGPT-compatible search" essentially restate the tool name and title without naming a domain, corpus, or scope. With two sibling search tools (search_articles, search_word_study) present, the agent has no basis for telling them apart. The only content ('returns id, title, url, text') describes output, not purpose.

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

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

There is no when-to-use guidance and no mention of the sibling search tools or the fetch/get_article tools it might complement. The cryptic "[no key]" tag does not tell the agent which situations should route here. Any usage routing is left entirely to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description's one added behavioral fact is the 'published' scope (excluding drafts), which is genuinely useful; the trailing '[no key]' is opaque and adds no actionable 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?

Single front-loaded clause with no filler sentences. The bracketed '[no key]' fragment is cryptic enough to be mild noise rather than a useful addition.

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

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

For a 3-param search tool with no output schema and 0% schema coverage, the description omits parameter meaning, return shape/result ordering, and routing versus siblings. Only the published-articles scope is established.

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

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

Schema description coverage is 0% for all three parameters, so the description must carry the burden and it doesn't. 'by title, description, tags, and shelf' loosely maps to search targets but never explains what 'query' is versus 'shelf', and 'limit' is entirely unaddressed.

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

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

States a specific verb (search) and resource (published articles) plus the fields searched, which separates it from get_article/list_articles. It stops short of explicitly naming the sibling it competes with, so it's clear but not sibling-differentiated in the strongest sense.

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

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

No when-to-use, when-not-to-use, or alternative is given. An agent can infer it's a search tool, but nothing tells it why to pick this over find_articles_for_claim, related_articles, or list_articles.

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 read-only, idempotent, non-destructive behavior, and the description doesn't contradict them. It adds that searches can span four input types, which is useful context, but says nothing about result limits, authentication, or rate behavior; '[no key]' is too cryptic to count as clear disclosure.

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

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

One front-loaded sentence with no filler, followed by a compact bracketed note. The note '[no key]' is ambiguous and slightly harms structure, but overall it is appropriately sized.

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 lemma search with an output schema and safety annotations, the description covers purpose and query semantics well enough. It omits limit behavior and usage alternatives, but those gaps are minor given the schema's bounds and the output schema handling 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that the required query can be a gloss, transliteration, lemma, or Strong's number, which compensates for the query parameter, but it says nothing about the optional limit parameter (1–20).

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 ('Find') and resource ('Greek or Hebrew lemmas') and enumerates the searchable fields, which distinguishes it from retrieval tools like get_word_study. It doesn't explicitly name a sibling alternative, but the scope is unambiguous.

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

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

Implies usage when one has a gloss, transliteration, lemma, or Strong's number, but offers no explicit when-to-use or when-not guidance and does not point to alternatives like get_word_study. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The bracketed '[no key]' arguably adds useful auth context (no API key required), but it is cryptic and adds nothing about return size or format.

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 fragment-list with no wasted sentences. The trailing '[no key]' tag is underspecified and reads like an internal note rather than agent-facing prose, which is a minor structural blemish.

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

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

With no output schema and no parameters, the description carries the burden of conveying what comes back, and it only lists content categories without saying what llms.txt, skill.md, or Connect actually contain or how an agent should use them. Adequate for an orientation tool, but thin.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals a no-input call by not implying any arguments.

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 enumerates exactly what the tool returns (mission, shelves, citation guidance, links to llms.txt/skill.md/Connect), which is enough to distinguish it from retrieval siblings like get_article or list_shelves. It lacks an explicit verb and never contrasts itself with alternatives, but no sibling overlaps this 'site overview' 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?

There is no guidance on when to call this: no mention of orientation/onboarding use, no prerequisites, and no routing away from overlapping tools such as list_shelves (which the description's 'shelves' mention could easily confuse). Usage must be inferred entirely.

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

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

Adds substantial context beyond the annotations: a spam and abuse check runs first, passing changes are stored as pending and are explicitly NOT published, and sign-in is required. These are exactly the moderation-pipeline and auth facts an agent needs and that readOnlyHint/destructiveHint cannot convey.

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

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

Three short sentences, front-loaded with the core action and followed by the moderation outcome and auth requirement. No filler; every clause carries 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?

The workflow (check, pending, unpublished) and auth requirement are well covered, but for a five-parameter mutation tool with 0% schema coverage and no output schema, the absence of any parameter guidance leaves an agent guessing at field meanings. Adequate on process, incomplete on inputs.

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

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

Schema description coverage is 0% across five parameters (path, summary, detail, sources, proposed_markdown), and the description mentions none of them. Nothing explains what path refers to, that summary is a short 140-char abstract, or that proposed_markdown carries the actual replacement content – the description does not compensate for the coverage gap.

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

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

States a specific verb and resource: submitting a change to a published page. The 'published page' scope implicitly separates it from propose_new_article and suggest_topic, but no sibling is named explicitly, so the differentiation is left to inference.

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

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

Usage is implied by 'a published page' – this is for edits to existing content rather than new articles or topics – but the description never says when to use this versus propose_new_article or how to follow up via my_suggestions. No exclusions or prerequisites beyond the sign-in note.

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 add nothing about auth, but the description supplies '[sign-in required]', which is valuable context beyond the structured fields. It also discloses the interactive reply behavior (linking a match and asking what it doesn't answer) and the queueing side effect, consistent with readOnlyHint=false and destructiveHint=false.

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

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

Front-loaded with the core purpose and kept to two compact sentences with no filler, though the middle clause ('asks what it does not answer') is slightly convoluted and could be clearer.

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 non-idempotent mutation tool with no output schema and 0% schema description coverage, the description covers the sign-in gate and submission workflow but omits what the call returns and the role of two parameters. Adequate but incomplete given the complexity.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, yet it only gestures at 'title' and explains 'explainer' in workflow terms. The 'sources' and 'summary' parameters are left entirely undocumented in both schema and description, a significant gap for a 4-parameter 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?

States a specific verb+resource ('Suggest an article title or topic'), which is clear on its own. However, it does not differentiate from the very similar sibling tools propose_new_article and suggest_article_change, leaving an agent to guess which submission path 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?

It describes a conditional workflow – when a published article is a close match, the reply links it and the user should send the answer gap as 'explainer' to queue the topic. This implies usage but never states when to prefer this tool over propose_new_article or suggest_article_change, so routing guidance is incomplete.

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

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

Annotations already declare this a safe, read-only, idempotent, non-destructive call, so the safety profile is covered. The description adds meaningful context beyond that: the sign-in requirement and the fact that the quota value is scoped to 'today'. It does not discuss caching or how quota consumption updates, which would be the remaining gap.

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

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

A single terse sentence with the most useful field list front-loaded and the prerequisite tucked into a short bracketed tag. No sentence is wasted and nothing needs to be skimmed past to get the essentials.

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 tool with full annotation coverage, the description is nearly self-sufficient: it names the return fields, which partly stands in for the absent output schema, and flags the auth requirement. The only minor omission is any note on how the daily quota resets or what happens when it is exhausted.

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

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

There are zero parameters, so per the rubric the baseline is 4. The description instead documents the response fields, which is helpful but not strictly a parameter concern.

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 enumerates exactly what the tool returns — account id, display name, role, and today's remaining suggestion quota — so an agent can tell it apart from siblings like site_summary or list_saved. It lacks an explicit verb such as 'returns' or 'fetches', leaving the action slightly implied rather than stated.

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

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

The bracketed '[sign-in required]' states a genuine prerequisite, which is useful guidance. However, it offers no when-to-use framing, no exclusions, and names no alternative sibling for obtaining account information, so usage remains implied.

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