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 fully covered without description help. The description adds that complexity is heuristic and that a calibrated rate is optional, but it does not explain how complexity is computed or what the summary contains.

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 with no wasted clauses, and the core purpose is front-loaded. The brevity is efficient but tips into under-specification.

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, 0% parameter descriptions, and a required 'path' argument, the description must carry more weight than it does. It omits the expected path format, what the complexity score means, and what the summary 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?

Schema description coverage is 0%, so the description must compensate and largely fails. 'path' — the required parameter — is never mentioned, and the 'hourly rate' phrasing does not clearly map to the 'hours_per_point' parameter, whose units and effect on output remain undefined.

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 concrete verb+resource: 'Summarize Forms metadata and heuristic complexity.' An agent can tell this is an analysis/summary tool rather than a raw fetch like get_source or an enumeration like list_forms. However, 'heuristic complexity' is unexplained jargon, so the exact output is somewhat opaque.

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 none of the siblings (list_forms, migration_risks, plan_apex) are named as alternatives. The optional hourly-rate clause hints at cost/effort estimation but never states the scenario that should trigger this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false; the description adds the useful clarification that 'no SQL is executed', which tells the agent the tool only generates artifacts. It does not say whether the drafts are persisted anywhere, what happens to prior drafts, or what permissions are needed.

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

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

A single front-loaded sentence that names the outputs first and the safety caveat last; nothing is wasted. It is perhaps too terse given the parameter gap, but as structure it is clean.

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

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

No output schema and zero parameter documentation mean the description must carry the load, but it says nothing about the shape of the returned artifacts, where they are written, or how the three required identifiers are used. For a generator with three required inputs this leaves real ambiguity.

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?

All three parameters (path, block_name, package_name) are required yet schema description coverage is 0%, and the description never mentions any of them. An agent gets no hint about format or meaning of 'path' versus 'block_name', so the description fails to compensate for the empty schema.

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

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

States a clear verb ('Return') and three concrete artifacts: PL/SQL stubs, an unpublished ORDS definition and a draft OpenAPI contract. That is far more specific than the name, though it does not relate itself to any sibling tool (the siblings are mostly inspection/planning tools, so differentiation is arguably irrelevant).

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 word 'draft' plus 'unpublished' implies this is for scaffolding an API before publishing it, but the description never states when to prefer it over other tools or what preconditions exist. Usage must be inferred from the artifact names rather than being stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so safety is covered. The description usefully adds that output is returned in character chunks (i.e., results may be truncated and require pagination) and clarifies a line-numbering convention against the full source, but it omits chunk size behavior and how to iterate.

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 with two clauses, both of which carry information: the read mode and a caveat about line-number semantics. It is front-loaded and wastes no words, though the semicolon-joined caveat could be more clearly separated.

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 four-parameter read tool with zero schema coverage and no output schema, the description does too little: an agent cannot tell what path means relative to component_id, nor how to page through chunks. The chunking hint is the only guidance offered.

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 all four parameters (path, component_id, limit, offset) arrive with bare titles and no meaning. 'Character chunks' indirectly implies that limit/offset are chunking controls, but the description never explains what path vs component_id represent or how they relate, leaving the required-parameter pair effectively undocumented.

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

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

The description states a concrete verb and resource ('Read original code') plus a retrieval mode ('in character chunks'), which is clear enough to separate it from analysis-oriented siblings like analyze_form or migration_risks. It does not explicitly name or contrast with any sibling, keeping it short of a 5.

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

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

The clause about risk line numbers referring to the complete component source implies this tool is the follow-up to migration_risks, but the connection is only hinted at rather than spelled out. There is no explicit guidance on when to prefer this tool over analyze_form or when not 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 already establish readOnly/idempotent/non-destructive/openWorld, and the description adds genuinely new constraints: the queries are 'fixed' (no arbitrary SQL), results are capped at 20 objects, and scope is limited to the server-configured schema. It does not say what happens above the 20-object cap or what an unrecognized name 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?

A single front-loaded sentence with no filler; the constraint (20 objects, fixed queries) arrives immediately.

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

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

With one param and no output schema, the description covers intent and scope but not the shape of results or error behavior for missing/overflow names, which an agent would want before relying on it.

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

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

One parameter at 0% schema coverage, so the description must carry it. It discloses the array is object names and the cap of 20, but leaves qualification/case sensitivity and item-level constraints unspecified.

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

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

Specific verb (Read) plus concrete resource (Oracle dictionary queries over database objects), with scope qualifiers (up to 20 objects, server-configured schema). An agent can tell this is a metadata-inspection tool rather than a form/Apex tool, though it never names a sibling to contrast with.

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 statement of when to prefer this over get_source or list_components, no prerequisites, no exclusions. The agent must infer usage from the verb alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered, but the description adds no behavioral context of its own: it does not say whether results are paginated (limit defaults to 100), what order they come in, or how deep the listing goes. With annotations carrying the full safety profile, the description contributes almost nothing beyond the safety story.

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

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

Two short sentences, front-loaded with what is listed before the argument hint. Nothing is wasted, though the terseness edges toward under-specification rather than efficient density.

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

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

A four-parameter tool with 0% schema coverage and no output schema needs the description to explain the required path, the component kinds, and pagination behavior. The description leaves the required parameter and the return shape entirely 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%, so the description must compensate, and it only covers 'kind' (with example values Trigger/Item and the blank-means-all default). The required 'path' parameter is never explained, and limit/offset pagination semantics are left completely undocumented.

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

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

The verb 'List' plus the enumeration 'blocks/items/triggers/program units' conveys the resource, but the umbrella term 'components' is never defined and the description does not distinguish this tool from siblings like list_forms or inspect_database_objects, which plausibly overlap.

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 only guidance is about the 'kind' argument ('Use exact kind... blank means all'), which is parameter syntax, not when-to-use. There is no statement of when to pick this tool over list_forms or inspect_database_objects, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds only that results are paginated, with no note on ordering, total counts, or error conditions, so it adds modest value beyond structured data.

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

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

A single front-loaded sentence with the scope and behavior stated up front and zero wasted words. Well sized for a simple read tool.

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

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

For a trivial read-only listing tool this is close to adequate, and annotations cover safety. However, with no output schema and no description of what each returned form entry contains or how pagination terminates, an agent still lacks return-value context.

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

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

Schema coverage is 0% — neither the 'limit' nor 'offset' parameter has a description. The phrase 'with pagination' merely hints that limit/offset control paging without defining defaults (100/0), maximums, or behavior at the end of the list, so the gap is largely uncompensated.

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 XML files') plus the scope ('within the configured Forms root'). It implicitly distinguishes the resource (forms) from the sibling list_components, but never explicitly contrasts the two, 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 guidance on when to use this versus siblings like analyze_form, list_components, or get_source, and no prerequisites or exclusions. Usage is only inferable 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 a read-only, idempotent, closed-world, non-destructive operation, so the safety profile is covered. The description adds that results come with 'source evidence', which is genuinely useful context about the response, but says nothing about pagination behavior or how risks are ranked.

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

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

A single dense sentence with the risk categories front-loaded after the verb; nothing is redundant. It is compact to the point of omitting needed detail, but the brevity itself is well-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, no parameter descriptions, and no annotations explaining results, the description should say what 'source evidence' looks like (file/line references?) and how the path argument is interpreted. Neither is present, leaving the agent under-informed for a three-parameter invocation.

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

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

Schema description coverage is 0%, so the description must carry all meaning for the three parameters and it carries none: 'path' (the only required argument) is never explained as a source root vs. a Form module, and limit/offset are only discoverable from the schema defaults. This is a significant gap for an otherwise scoped analysis 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 (find) and a concrete resource (Forms migration risks across navigation, session, integration, dynamic-SQL and transaction categories), with the notable output promise of 'source evidence'. The risk taxonomy makes it clearly distinguishable from siblings like analyze_form or plan_apex, though it does not name any sibling explicitly.

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

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

There is no statement of when to run this versus analyze_form or plan_apex, no prerequisite (e.g. must the codebase be indexed first), and no exclusion criteria. An agent can only infer usage from the migration-testing framing of the sentence.

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 the description usefully reinforces that boundary by disclaiming export creation — an agent could otherwise assume 'build' produces artifacts. It still doesn't say whether the draft is returned as text or written somewhere, which matters for a non-destructive tool.

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

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

Two short sentences, no padding, with the purpose front-loaded and the exclusion immediately after. Efficient, though the extreme terseness is what leaves the gaps flagged elsewhere.

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

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

No output schema exists, so the description should explain what a 'draft mapping and acceptance checklist' looks like or where it lands; it doesn't. Combined with the undocumented 'path' argument, an agent cannot confidently construct a correct 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?

There is a single required 'path' parameter with 0% schema description coverage, and the description says nothing about it — path to an APEX app, a directory, a form definition? With low coverage the description must compensate and it 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 gives a concrete verb and artifact: builds a draft APEX region/trigger mapping plus an acceptance checklist. It is distinguishable from siblings like draft_api and migration_risks, though it never names them. Purpose is clear, sibling routing is implicit.

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 only usage signal is the negative scope 'Does not create an APEX export', which implies this is a pre-export planning step. There is no explicit guidance on when to call this versus analyze_form, migration_risks, or draft_api, nor any stated prerequisites.

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